[PATCH] (revised) Make definition of "command" more accessible in Lispref.

Revised, in response to Stephen’s comments in 878y6qdv8y.fsf(a)tleepslib.sk.tsukuba.ac.jp , to rename the node globally, and to change a couple of “pxref”s to “xref”s. 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-19 Aidan Kehoe <kehoea(a)parhasard.net&gt; * man/lispref/functions.texi (Functions): Rename to "Functions and Commands" * man/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). * man/lispref/eval.texi man/lispref/lispref.texi man/lispref/macros.texi man/lispref/mule.texi man/lispref/symbols.texi man/lispref/variables.texi: Fix cross references XEmacs Current source patch: Diff command: cvs -q diff -u Files affected: man/lispref/eval.texi man/lispref/functions.texi man/lispref/lispref.texi man/lispref/macros.texi man/lispref/mule.texi man/lispref/symbols.texi man/lispref/variables.texi Index: man/lispref/eval.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/eval.texi,v retrieving revision 1.5 diff -u -r1.5 eval.texi --- man/lispref/eval.texi 2001/04/12 18:22:13 1.5 +++ man/lispref/eval.texi 2005/01/19 10:40:00 ＠＠ -74,7 +74,7 ＠＠ function ＠code{car}. Evaluation of a function call ultimately calls the function specified -in it. ＠xref{Functions}. The execution of the function may itself work +in it. ＠xref{Functions and Commands}. The execution of the function may itself work by evaluating the function definition; or the function may be a Lisp primitive implemented in C, or it may be a byte-compiled function (＠pxref{Byte Compilation}). 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/19 10:40:03 ＠＠ -3,8 +3,8 ＠＠ ＠c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. ＠c See the file lispref.texi for copying conditions. ＠setfilename ../../info/functions.info -＠node Functions, Macros, Variables, Top -＠chapter Functions +＠node Functions and Commands, Macros, Variables, Top +＠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 ＠xref{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 ＠xref{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 Index: man/lispref/lispref.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/lispref.texi,v retrieving revision 1.20 diff -u -r1.20 lispref.texi --- man/lispref/lispref.texi 2004/07/19 08:24:28 1.20 +++ man/lispref/lispref.texi 2005/01/19 10:40:06 ＠＠ -144,8 +144,10 ＠＠ * Evaluation:: How Lisp expressions are evaluated. * Control Structures:: Conditionals, loops, nonlocal exits. * Variables:: Using symbols in programs to stand for values. -* Functions:: A function is a Lisp program - that can be invoked from other functions. + +* Functions and Commands:: A function is a Lisp program that can be + invoked from other functions. + * Macros:: Macros are a way to extend the Lisp language. * Customization:: Writing customization declarations. Index: man/lispref/macros.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/macros.texi,v retrieving revision 1.2 diff -u -r1.2 macros.texi --- man/lispref/macros.texi 2001/04/12 18:22:17 1.2 +++ man/lispref/macros.texi 2005/01/19 10:40:06 ＠＠ -3,7 +3,7 ＠＠ ＠c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. ＠c See the file lispref.texi for copying conditions. ＠setfilename ../../info/macros.info -＠node Macros, Loading, Functions, Top +＠node Macros, Loading, Functions and Commands, Top ＠chapter Macros ＠cindex macros Index: man/lispref/mule.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/mule.texi,v retrieving revision 1.11 diff -u -r1.11 mule.texi --- man/lispref/mule.texi 2004/11/04 23:06:07 1.11 +++ man/lispref/mule.texi 2005/01/19 10:40:08 ＠＠ -2056,7 +2056,23 ＠＠ ＠comment Node, Next, Previous, Up ＠subsection CCL Examples - This section is not yet written. +CCL isn't an especially nice language to program in, compared to Emacs +lisp, but writing coding systems in it is a huge improvement in +stability and convenience over writing them in XEmacs' C core, which is +the alternative. So for that reason, it's worth learning, should you +need or want to transform data with in the coding system framework. + +This section describes the implementation, in CCL, of a coding system to +transform from the standard GSM coding system, as used for SMS text +messages in your mobile phone, to XEmacs' internal format. (Yes, for the +detail-oriented among you, if you're in East Asia you probably send SMS +messages using UCS-2. But, if you're in East Asia, you're more likely to +be sending email from your phone than text messages anyway.) + +The GSM coding system is a seven-bit, packed, variable length +encoding. This means that characters + + ＠node Category Tables, Unicode Support, CCL, MULE ＠section Category Tables Index: man/lispref/symbols.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/symbols.texi,v retrieving revision 1.4 diff -u -r1.4 symbols.texi --- man/lispref/symbols.texi 2001/04/12 18:22:21 1.4 +++ man/lispref/symbols.texi 2005/01/19 10:40:09 ＠＠ -11,8 +11,8 ＠＠ describes symbols, their components, their property lists, and how they are created and interned. Separate chapters describe the use of symbols as variables and as function names; see ＠ref{Variables}, and -＠ref{Functions}. For the precise read syntax for symbols, see -＠ref{Symbol Type}. +＠ref{Functions and Commands}. For the precise read syntax for symbols, +see ＠ref{Symbol Type}. You can test whether an arbitrary Lisp object is a symbol with ＠code{symbolp}: ＠＠ -154,7 +154,7 ＠＠ cell, is derived from the idea that ＠code{defun} gives the symbol its definition as a function.) ＠code{defsubst}, ＠code{define-function} and ＠code{defalias} are other ways of defining a function. -＠xref{Functions}. +＠xref{Functions and Commands}. ＠code{defmacro} defines a symbol as a macro. It creates a macro object and stores it in the function cell of the symbol. Note that a Index: man/lispref/variables.texi =================================================================== RCS file: /pack/xemacscvs/XEmacs/xemacs/man/lispref/variables.texi,v retrieving revision 1.6 diff -u -r1.6 variables.texi --- man/lispref/variables.texi 2002/10/02 09:30:52 1.6 +++ man/lispref/variables.texi 2005/01/19 10:40:09 ＠＠ -3,7 +3,7 ＠＠ ＠c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. ＠c See the file lispref.texi for copying conditions. ＠setfilename ../../info/variables.info -＠node Variables, Functions, Control Structures, Top +＠node Variables, Functions and Commands, Control Structures, Top ＠chapter Variables ＠cindex variable ＠＠ -225,7 +225,7 ＠＠ ＠itemize ＠bullet ＠item -Function calls (＠pxref{Functions}). +Function calls (＠pxref{Functions and Commands}). ＠item Macro calls (＠pxref{Macros}). -- “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.”