From 03988c98dfbb4506ada95f52e4a34071627c3b49 Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sun, 5 Feb 2012 14:44:47 +0800 Subject: [PATCH] Updates to Macros and Customization chapters of Lisp manual. * doc/lispref/customize.texi (Common Keywords): Minor clarifications. Document custom-unlispify-remove-prefixes. (Variable Definitions): Backquotes in defcustom seem to work fine now. Various other copyedits. * doc/lispref/macros.texi (Expansion): Minor clarification. (Backquote): Move node to eval.texi. (Defining Macros): Move an example from Backquote node. (Argument Evaluation): No need to mention Pascal. (Indenting Macros): Add xref to Defining Macros. * doc/lispref/eval.texi (Backquote): Move from macros.texi. * lisp/custom.el (defcustom): Doc fix. --- admin/FOR-RELEASE | 2 +- doc/lispref/ChangeLog | 15 ++++ doc/lispref/customize.texi | 123 ++++++++++++++------------------ doc/lispref/elisp.texi | 2 +- doc/lispref/eval.texi | 91 ++++++++++++++++++++++++ doc/lispref/macros.texi | 142 +++++++++---------------------------- doc/lispref/vol1.texi | 2 +- doc/lispref/vol2.texi | 2 +- lisp/ChangeLog | 4 ++ lisp/custom.el | 6 +- 10 files changed, 202 insertions(+), 187 deletions(-) diff --git a/admin/FOR-RELEASE b/admin/FOR-RELEASE index 34c9c4bb21c..74a758826a1 100644 --- a/admin/FOR-RELEASE +++ b/admin/FOR-RELEASE @@ -208,7 +208,7 @@ keymaps.texi lists.texi cyd loading.texi locals.texi -macros.texi +macros.texi cyd maps.texi markers.texi minibuf.texi diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 65740feeee5..bd7b27bbe60 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,18 @@ +2012-02-05 Chong Yidong + + * customize.texi (Common Keywords): Minor clarifications. + Document custom-unlispify-remove-prefixes. + (Variable Definitions): Backquotes in defcustom seem to work fine + now. Various other copyedits. + + * eval.texi (Backquote): Move from macros.texi. + + * macros.texi (Expansion): Minor clarification. + (Backquote): Move node to eval.texi. + (Defining Macros): Move an example from Backquote node. + (Argument Evaluation): No need to mention Pascal. + (Indenting Macros): Add xref to Defining Macros. + 2012-02-05 Glenn Morris * debugging.texi (Error Debugging): Mention debug-on-event default. diff --git a/doc/lispref/customize.texi b/doc/lispref/customize.texi index 6d6c5df10ed..b8c30fff8ae 100644 --- a/doc/lispref/customize.texi +++ b/doc/lispref/customize.texi @@ -24,9 +24,10 @@ definitions---as well as face definitions (@pxref{Defining Faces}). @section Common Item Keywords @cindex customization keywords - All kinds of customization declarations (for variables and groups, and -for faces) accept keyword arguments for specifying various information. -This section describes some keywords that apply to all kinds. + The customization declarations that we will describe in the next few +sections (@code{defcustom}, @code{defgroup}, etc.) all accept keyword +arguments for specifying various information. This section describes +keywords that apply to all types of customization declarations. All of these keywords, except @code{:tag}, can be used more than once in a given item. Each use of the keyword has an independent effect. @@ -108,8 +109,7 @@ You can specify the text to use in the customization buffer by adding for example, @code{(info-link :tag "foo" "(emacs)Top")} makes a link to the Emacs manual which appears in the buffer as @samp{foo}. -An item can have more than one external link; however, most items have -none at all. +You can use this keyword more than once, to add multiple links. @item :load @var{file} @kindex load@r{, customization keyword} @@ -136,14 +136,13 @@ version. The value @var{version} must be a string. @kindex package-version@r{, customization keyword} This keyword specifies that the item was first introduced in @var{package} version @var{version}, or that its meaning or default -value was changed in that version. The value of @var{package} is a -symbol and @var{version} is a string. +value was changed in that version. This keyword takes priority over +@code{:version}. -This keyword takes priority over @code{:version}. - -@var{package} should be the official name of the package, such as MH-E -or Gnus. If the package @var{package} is released as part of Emacs, -@var{package} and @var{version} should appear in the value of +@var{package} should be the official name of the package, as a symbol +(e.g.@: @code{MH-E}). @var{version} should be a string. If the +package @var{package} is released as part of Emacs, @var{package} and +@var{version} should appear in the value of @code{customize-package-emacs-version-alist}. @end table @@ -226,41 +225,31 @@ also use this keyword in @code{defgroup}: @table @code @item :prefix @var{prefix} @kindex prefix@r{, @code{defgroup} keyword} -If the name of an item in the group starts with @var{prefix}, then the -tag for that item is constructed (by default) by omitting @var{prefix}. - -One group can have any number of prefixes. +If the name of an item in the group starts with @var{prefix}, and the +customizable variable @code{custom-unlispify-remove-prefixes} is +non-@code{nil}, the item's tag will omit @var{prefix}. A group can +have any number of prefixes. @end table @end defmac - The prefix-discarding feature is currently turned off, which means -that @code{:prefix} currently has no effect. We did this because we -found that discarding the specified prefixes often led to confusing -names for options. This happened because the people who wrote the -@code{defgroup} definitions for various groups added @code{:prefix} -keywords whenever they make logical sense---that is, whenever the -variables in the library have a common prefix. - - In order to obtain good results with @code{:prefix}, it would be -necessary to check the specific effects of discarding a particular -prefix, given the specific items in a group and their names and -documentation. If the resulting text is not clear, then @code{:prefix} -should not be used in that case. +@defopt custom-unlispify-remove-prefixes +If this variable is non-@code{nil}, the prefixes specified by a +group's @code{:prefix} keyword are omitted from tag names, whenever +the user customizes the group. - It should be possible to recheck all the customization groups, delete -the @code{:prefix} specifications which give unclear results, and then -turn this feature back on, if someone would like to do the work. +The default value is @code{nil}, i.e.@: the prefix-discarding feature +is disabled. This is because discarding prefixes often leads to +confusing names for options and faces. +@end defopt @node Variable Definitions @section Defining Customization Variables @cindex define customization options @cindex customization variables, how to define - Use @code{defcustom} to declare user-customizable variables. - @defmac defcustom option standard doc [keyword value]@dots{} -This macro declares @var{option} as a customizable @dfn{user option}. -You should not quote @var{option}. +This macro declares @var{option} as a user option (i.e.@: a +customizable variable). You should not quote @var{option}. The argument @var{standard} is an expression that specifies the standard value for @var{option}. Evaluating the @code{defcustom} form @@ -275,31 +264,25 @@ cases applies, @code{defcustom} installs the result of evaluating The expression @var{standard} can be evaluated at various other times, too---whenever the customization facility needs to know @var{option}'s standard value. So be sure to use an expression which is harmless to -evaluate at any time. We recommend avoiding backquotes in -@var{standard}, because they are not expanded when editing the value, -so list values will appear to have the wrong structure. +evaluate at any time. The argument @var{doc} specifies the documentation string for the variable. Every @code{defcustom} should specify @code{:group} at least once. -If you specify the @code{:set} keyword, to make the variable take other -special actions when set through the customization buffer, the -variable's documentation string should tell the user specifically how -to do the same job in hand-written Lisp code. - When you evaluate a @code{defcustom} form with @kbd{C-M-x} in Emacs Lisp mode (@code{eval-defun}), a special feature of @code{eval-defun} arranges to set the variable unconditionally, without testing whether its value is void. (The same feature applies to @code{defvar}.) @xref{Defining Variables}. -If you put a @code{defcustom} in a file that is preloaded at dump time -(@pxref{Building Emacs}), and the standard value installed for the -variable at that time might not be correct, use +If you put a @code{defcustom} in a pre-loaded Emacs Lisp file +(@pxref{Building Emacs}), the standard value installed at dump time +might be incorrect, e.g.@: because another variable that it depends on +has not been assigned the right value yet. In that case, use @code{custom-reevaluate-setting}, described below, to re-evaluate the -standard value during or after Emacs startup. +standard value after Emacs starts up. @end defmac @code{defcustom} accepts the following additional keywords: @@ -330,6 +313,9 @@ the value properly for this option (which may not mean simply setting the option as a Lisp variable). The default for @var{setfunction} is @code{set-default}. +If you specify this keyword, the variable's documentation string +should describe how to do the same job in hand-written Lisp code. + @item :get @var{getfunction} @kindex get@r{, @code{defcustom} keyword} Specify @var{getfunction} as the way to extract the value of this @@ -341,7 +327,7 @@ value). The default is @code{default-value}. You have to really understand the workings of Custom to use @code{:get} correctly. It is meant for values that are treated in Custom as variables but are not actually stored in Lisp variables. It -is almost surely a mistake to specify @code{getfunction} for a value +is almost surely a mistake to specify @var{getfunction} for a value that really is stored in a Lisp variable. @item :initialize @var{function} @@ -380,16 +366,15 @@ already set or has been customized; otherwise, just use These functions behave like @code{custom-initialize-set} (@code{custom-initialize-default}, respectively), but catch errors. If an error occurs during initialization, they set the variable to -@code{nil} using @code{set-default}, and throw no error. - -These two functions are only meant for options defined in pre-loaded -files, where some variables or functions used to compute the option's -value may not yet be defined. The option normally gets updated in -@file{startup.el}, ignoring the previously computed value. Because of -this typical usage, the value which these two functions compute -normally only matters when, after startup, one unsets the option's -value and then reevaluates the defcustom. By that time, the necessary -variables and functions will be defined, so there will not be an error. +@code{nil} using @code{set-default}, and signal no error. + +These functions are meant for options defined in pre-loaded files, +where the @var{standard} expression may signal an error because some +required variable or function is not yet defined. The value normally +gets updated in @file{startup.el}, ignoring the value computed by +@code{defcustom}. After startup, if one unsets the value and +reevaluates the @code{defcustom}, the @var{standard} expression can be +evaluated without error. @end table @item :risky @var{value} @@ -457,18 +442,16 @@ is an expression that evaluates to the value. @defun custom-reevaluate-setting symbol This function re-evaluates the standard value of @var{symbol}, which -should be a user option declared via @code{defcustom}. (If the +should be a user option declared via @code{defcustom}. If the variable was customized, this function re-evaluates the saved value -instead.) This is useful for customizable options that are defined -before their value could be computed correctly, such as variables -defined in packages that are loaded at dump time, but depend on the -run-time information. For example, the value could be a file whose -precise name depends on the hierarchy of files when Emacs runs, or a -name of a program that needs to be searched at run time. - -A good place to put calls to this function is in the function -@code{command-line} that is run during startup (@pxref{Startup Summary}) -or in the various hooks it calls. +instead. Then it sets the user option to that value (using the +option's @code{:set} property if that is defined). + +This is useful for customizable options that are defined before their +value could be computed correctly. For example, during startup Emacs +calls this function for some user options that were defined in +pre-loaded Emacs Lisp files, but whose initial values depend on +information available only at run-time. @end defun @defun custom-variable-p arg diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index b4692cd33ce..f69823101d0 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -374,6 +374,7 @@ Evaluation * Forms:: How various sorts of objects are evaluated. * Quoting:: Avoiding evaluation (to put constants in the program). +* Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. Kinds of Forms @@ -482,7 +483,6 @@ Macros * Expansion:: How, when and why macros are expanded. * Compiling Macros:: How macros are expanded by the compiler. * Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. * Problems with Macros:: Don't evaluate the macro arguments too many times. Don't hide the user's variables. * Indenting Macros:: Specifying how to indent macro calls. diff --git a/doc/lispref/eval.texi b/doc/lispref/eval.texi index e81efd10892..cb3a4c54fac 100644 --- a/doc/lispref/eval.texi +++ b/doc/lispref/eval.texi @@ -23,6 +23,7 @@ function @code{eval}. * Intro Eval:: Evaluation in the scheme of things. * Forms:: How various sorts of objects are evaluated. * Quoting:: Avoiding evaluation (to put constants in the program). +* Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. @end menu @@ -579,6 +580,96 @@ Functions}), which causes an anonymous lambda expression written in Lisp to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote only part of a list, while computing and substituting other parts. +@node Backquote +@section Backquote +@cindex backquote (list substitution) +@cindex ` (list substitution) +@findex ` + + @dfn{Backquote constructs} allow you to quote a list, but +selectively evaluate elements of that list. In the simplest case, it +is identical to the special form @code{quote} +@iftex +@end iftex +@ifnottex +(described in the previous section; @pxref{Quoting}). +@end ifnottex +For example, these two forms yield identical results: + +@example +@group +`(a list of (+ 2 3) elements) + @result{} (a list of (+ 2 3) elements) +@end group +@group +'(a list of (+ 2 3) elements) + @result{} (a list of (+ 2 3) elements) +@end group +@end example + +@findex , @r{(with backquote)} + The special marker @samp{,} inside of the argument to backquote +indicates a value that isn't constant. The Emacs Lisp evaluator +evaluates the argument of @samp{,}, and puts the value in the list +structure: + +@example +@group +`(a list of ,(+ 2 3) elements) + @result{} (a list of 5 elements) +@end group +@end example + +@noindent +Substitution with @samp{,} is allowed at deeper levels of the list +structure also. For example: + +@example +@group +`(1 2 (3 ,(+ 4 5))) + @result{} (1 2 (3 9)) +@end group +@end example + +@findex ,@@ @r{(with backquote)} +@cindex splicing (with backquote) + You can also @dfn{splice} an evaluated value into the resulting list, +using the special marker @samp{,@@}. The elements of the spliced list +become elements at the same level as the other elements of the resulting +list. The equivalent code without using @samp{`} is often unreadable. +Here are some examples: + +@example +@group +(setq some-list '(2 3)) + @result{} (2 3) +@end group +@group +(cons 1 (append some-list '(4) some-list)) + @result{} (1 2 3 4 2 3) +@end group +@group +`(1 ,@@some-list 4 ,@@some-list) + @result{} (1 2 3 4 2 3) +@end group + +@group +(setq list '(hack foo bar)) + @result{} (hack foo bar) +@end group +@group +(cons 'use + (cons 'the + (cons 'words (append (cdr list) '(as elements))))) + @result{} (use the words foo bar as elements) +@end group +@group +`(use the words ,@@(cdr list) as elements) + @result{} (use the words foo bar as elements) +@end group +@end example + + @node Eval @section Eval diff --git a/doc/lispref/macros.texi b/doc/lispref/macros.texi index 3804d963108..dca88d2b7c7 100644 --- a/doc/lispref/macros.texi +++ b/doc/lispref/macros.texi @@ -27,7 +27,6 @@ instead. @xref{Inline Functions}. * Expansion:: How, when and why macros are expanded. * Compiling Macros:: How macros are expanded by the compiler. * Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. * Problems with Macros:: Don't evaluate the macro arguments too many times. Don't hide the user's variables. * Indenting Macros:: Specifying how to indent macro calls. @@ -78,10 +77,9 @@ to the argument values from the macro call, or to a list of them in the case of a @code{&rest} argument. And the macro body executes and returns its value just as a function body does. - The second crucial difference between macros and functions is that the -value returned by the macro body is not the value of the macro call. -Instead, it is an alternate expression for computing that value, also -known as the @dfn{expansion} of the macro. The Lisp interpreter + The second crucial difference between macros and functions is that +the value returned by the macro body is an alternate Lisp expression, +also known as the @dfn{expansion} of the macro. The Lisp interpreter proceeds to evaluate the expansion as soon as it comes back from the macro. @@ -221,7 +219,26 @@ any @code{interactive} declaration is ignored since macros cannot be called interactively. @end defspec - The body of the macro definition can include a @code{declare} form, + Macros often need to construct large list structures from a mixture +of constants and nonconstant parts. To make this easier, use the +@samp{`} syntax (@pxref{Backquote}). For example: + +@example +@example +@group +(defmacro t-becomes-nil (variable) + `(if (eq ,variable t) + (setq ,variable nil))) +@end group + +@group +(t-becomes-nil foo) + @equiv{} (if (eq foo t) (setq foo nil)) +@end group +@end example +@end example + + The body of a macro definition can include a @code{declare} form, which can specify how @key{TAB} should indent macro calls, and how to step through them for Edebug. @@ -259,107 +276,11 @@ without evaluating any @var{specs}. has no effect on how the macro expands, on what the macro means in the program. It only affects the secondary features listed above. -@node Backquote -@section Backquote -@cindex backquote (list substitution) -@cindex ` (list substitution) -@findex ` - - Macros often need to construct large list structures from a mixture of -constants and nonconstant parts. To make this easier, use the @samp{`} -syntax (usually called @dfn{backquote}). - - Backquote allows you to quote a list, but selectively evaluate -elements of that list. In the simplest case, it is identical to the -special form @code{quote} (@pxref{Quoting}). For example, these -two forms yield identical results: - -@example -@group -`(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@group -'(a list of (+ 2 3) elements) - @result{} (a list of (+ 2 3) elements) -@end group -@end example - -@findex , @r{(with backquote)} -The special marker @samp{,} inside of the argument to backquote -indicates a value that isn't constant. Backquote evaluates the -argument of @samp{,} and puts the value in the list structure: - -@example -@group -(list 'a 'list 'of (+ 2 3) 'elements) - @result{} (a list of 5 elements) -@end group -@group -`(a list of ,(+ 2 3) elements) - @result{} (a list of 5 elements) -@end group -@end example - - Substitution with @samp{,} is allowed at deeper levels of the list -structure also. For example: - -@example -@group -(defmacro t-becomes-nil (variable) - `(if (eq ,variable t) - (setq ,variable nil))) -@end group - -@group -(t-becomes-nil foo) - @equiv{} (if (eq foo t) (setq foo nil)) -@end group -@end example - -@findex ,@@ @r{(with backquote)} -@cindex splicing (with backquote) - You can also @dfn{splice} an evaluated value into the resulting list, -using the special marker @samp{,@@}. The elements of the spliced list -become elements at the same level as the other elements of the resulting -list. The equivalent code without using @samp{`} is often unreadable. -Here are some examples: - -@example -@group -(setq some-list '(2 3)) - @result{} (2 3) -@end group -@group -(cons 1 (append some-list '(4) some-list)) - @result{} (1 2 3 4 2 3) -@end group -@group -`(1 ,@@some-list 4 ,@@some-list) - @result{} (1 2 3 4 2 3) -@end group - -@group -(setq list '(hack foo bar)) - @result{} (hack foo bar) -@end group -@group -(cons 'use - (cons 'the - (cons 'words (append (cdr list) '(as elements))))) - @result{} (use the words foo bar as elements) -@end group -@group -`(use the words ,@@(cdr list) as elements) - @result{} (use the words foo bar as elements) -@end group -@end example - @node Problems with Macros @section Common Problems Using Macros - The basic facts of macro expansion have counterintuitive consequences. -This section describes some important consequences that can lead to + Macro expansion can have counterintuitive consequences. This +section describes some important consequences that can lead to trouble, and rules to follow to avoid trouble. @menu @@ -407,9 +328,8 @@ program is actually run. When defining a macro you must pay attention to the number of times the arguments will be evaluated when the expansion is executed. The -following macro (used to facilitate iteration) illustrates the problem. -This macro allows us to write a simple ``for'' loop such as one might -find in Pascal. +following macro (used to facilitate iteration) illustrates the +problem. This macro allows us to write a ``for'' loop construct. @findex for @smallexample @@ -683,9 +603,9 @@ either. @node Indenting Macros @section Indenting Macros - You can use the @code{declare} form in the macro definition to -specify how to @key{TAB} should indent calls to the macro. You -write it like this: + Within a macro definition, you can use the @code{declare} form +(@pxref{Defining Macros}) to specify how to @key{TAB} should indent +calls to the macro. An indentation specifiction is written like this: @example (declare (indent @var{indent-spec})) @@ -715,6 +635,7 @@ the line uses the standard pattern. @var{symbol} should be a function name; that function is called to calculate the indentation of a line within this expression. The function receives two arguments: + @table @asis @item @var{state} The value returned by @code{parse-partial-sexp} (a Lisp primitive for @@ -723,6 +644,7 @@ beginning of this line. @item @var{pos} The position at which the line being indented begins. @end table + @noindent It should return either a number, which is the number of columns of indentation for that line, or a list whose car is such a number. The diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 4a48536f5f3..0f4a4447ed3 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -390,6 +390,7 @@ Evaluation * Forms:: How various sorts of objects are evaluated. * Quoting:: Avoiding evaluation (to put constants in the program). +* Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. Kinds of Forms @@ -501,7 +502,6 @@ Macros * Expansion:: How, when and why macros are expanded. * Compiling Macros:: How macros are expanded by the compiler. * Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. * Problems with Macros:: Don't evaluate the macro arguments too many times. Don't hide the user's variables. * Indenting Macros:: Specifying how to indent macro calls. diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 961b3225823..241728fd1d2 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -389,6 +389,7 @@ Evaluation * Forms:: How various sorts of objects are evaluated. * Quoting:: Avoiding evaluation (to put constants in the program). +* Backquote:: Easier construction of list structure. * Eval:: How to invoke the Lisp interpreter explicitly. Kinds of Forms @@ -500,7 +501,6 @@ Macros * Expansion:: How, when and why macros are expanded. * Compiling Macros:: How macros are expanded by the compiler. * Defining Macros:: How to write a macro definition. -* Backquote:: Easier construction of list structure. * Problems with Macros:: Don't evaluate the macro arguments too many times. Don't hide the user's variables. * Indenting Macros:: Specifying how to indent macro calls. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 31be29953ae..d44e9d95636 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,7 @@ +2012-02-05 Chong Yidong + + * custom.el (defcustom): Doc fix. + 2012-02-05 Glenn Morris * font-lock.el (lisp-font-lock-keywords-2): Add with-wrapper-hook. diff --git a/lisp/custom.el b/lisp/custom.el index d9cba2704d8..962336978b1 100644 --- a/lisp/custom.el +++ b/lisp/custom.el @@ -229,6 +229,9 @@ The following keywords are meaningful: VALUE should be a feature symbol. If you save a value for this option, then when your `.emacs' file loads the value, it does (require VALUE) first. +:set-after VARIABLES + Specifies that SYMBOL should be set after the list of variables + VARIABLES when both have been customized. :risky Set SYMBOL's `risky-local-variable' property to VALUE. :safe Set SYMBOL's `safe-local-variable' property to VALUE. See Info node `(elisp) File Local Variables'. @@ -300,9 +303,6 @@ The following common keywords are also meaningful. Load file FILE (a string) before displaying this customization item. Loading is done with `load', and only if the file is not already loaded. -:set-after VARIABLES - Specifies that SYMBOL should be set after the list of variables - VARIABLES when both have been customized. If SYMBOL has a local binding, then this form affects the local binding. This is normally not what you want. Thus, if you need -- 2.39.2