[PATCH] Make the definition of what a command is more accessible in Lispref.

This is in response to a user who managed, quite quickly, to write some useful lisp code, but had real trouble finding out about the (interactive) declaration. The comp.emacs.xemacs thread starts at http://google.ie/groups?selm=1105972348.239860.235850＠c13g2000cwb.googleg... man/ChangeLog addition: 2005-01-18 Aidan Kehoe <kehoea(a)parhasard.net&gt; * lispref/functions.texi (Functions): Rename to "Functions and Commands" * lispref/functions.texi (What Is a Function): Move the definition of a command further up the list, give information on a trivial (interactive) declaration, and cross-reference to the key binding detail. Cf. 87vf9wgd08.fsf(a)tleepslib.sk.tsukuba.ac.jp (comp.emacs.xemacs, 2005-01-18). XEmacs Current source patch: Diff command: cvs -q diff -u Files affected: man/lispref/functions.texi Index: man/lispref/functions.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/functions.texi,v retrieving revision 1.2 diff -u -r1.2 functions.texi --- man/lispref/functions.texi 2001/04/12 18:22:14 1.2 +++ man/lispref/functions.texi 2005/01/18 23:20:30 ＠＠ -4,7 +4,7 ＠＠ ＠c See the file lispref.texi for copying conditions. ＠setfilename ../../info/functions.info ＠node Functions, Macros, Variables, Top -＠chapter Functions +＠chapter Functions and Commands A Lisp program is composed mainly of Lisp functions. This chapter explains what functions are, how they accept arguments, and how to ＠＠ -45,6 +45,39 ＠＠ specifically to mean a function written in Lisp. Special forms and macros are not functions. +＠item command +＠cindex command + +A ＠dfn{command} is a possible definition for a key sequence---we count +mouse events and menu accesses as key sequences for this purpose. More +formally, within XEmacs lisp, a command is something that +＠code{command-execute} can invoke. + +Some functions are commands; a function written in Lisp is a command if +it contains an interactive declaration. A trivial interactive +declaration is a line ＠code{(interactive)} immediately after the +documentation string. For more complex examples, with prompting and +completion, see ＠pxref{Defining Commands}. Such a function can be called +from Lisp expressions like other functions; in this case, the fact that +the function is a command makes no difference. + +Keyboard macros (strings and vectors) are commands also, even though +they are not functions. A symbol is a command if its function +definition is a command; such symbols can be invoked with ＠kbd{M-x}. +The symbol is a function as well if the definition is a function. + +In the case where you want to call a command in reaction to a +user-generated event, you'll need to bind it to that event. For how to +do this, see ＠pxref{Key Binding Commands}. +＠xref{Command Overview}. + +＠item keystroke command +＠cindex keystroke command +A ＠dfn{keystroke command} is a command that is bound to a key sequence +(typically one to three keystrokes). The distinction is made here +merely to avoid confusion with the meaning of ``command'' in non-Emacs +editors; for Lisp programs, the distinction is normally unimportant. + ＠item primitive ＠cindex primitive ＠cindex subr ＠＠ -83,28 +116,6 ＠＠ original expression. Macros enable Lisp programmers to do the sorts of things that special forms can do. ＠xref{Macros}, for how to define and use macros. - -＠item command -＠cindex command -A ＠dfn{command} is an object that ＠code{command-execute} can invoke; it -is a possible definition for a key sequence. Some functions are -commands; a function written in Lisp is a command if it contains an -interactive declaration (＠pxref{Defining Commands}). Such a function -can be called from Lisp expressions like other functions; in this case, -the fact that the function is a command makes no difference. - -Keyboard macros (strings and vectors) are commands also, even though -they are not functions. A symbol is a command if its function -definition is a command; such symbols can be invoked with ＠kbd{M-x}. -The symbol is a function as well if the definition is a function. -＠xref{Command Overview}. - -＠item keystroke command -＠cindex keystroke command -A ＠dfn{keystroke command} is a command that is bound to a key sequence -(typically one to three keystrokes). The distinction is made here -merely to avoid confusion with the meaning of ``command'' in non-Emacs -editors; for Lisp programs, the distinction is normally unimportant. ＠item compiled function A ＠dfn{compiled function} is a function that has been compiled by the -- “Ah come on now Ted, a Volkswagen with a mind of its own, driving all over the place and going mad, if that’s not scary I don’t know what is.”