X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/691b73f15393ac005c00ee3d544f3a4968c62b7e..2ea2a2f1a5b5b2e1b20f1ee8c86058334d0a2652:/doc/lispintro/emacs-lisp-intro.texi diff --git a/doc/lispintro/emacs-lisp-intro.texi b/doc/lispintro/emacs-lisp-intro.texi index 096b7bec28..eea46af6b1 100644 --- a/doc/lispintro/emacs-lisp-intro.texi +++ b/doc/lispintro/emacs-lisp-intro.texi @@ -1,4 +1,4 @@ -\input texinfo @c -*-texinfo-*- +\input texinfo @c -*- mode: texinfo; coding: utf-8 -*- @comment %**start of header @setfilename ../../info/eintr.info @c setfilename emacs-lisp-intro.info @@ -113,7 +113,7 @@ Edition @value{edition-number}, @value{update-date} Distributed with Emacs version @value{EMACSVER}. @end ifnottex @sp 1 -Copyright @copyright{} 1990--1995, 1997, 2001--2015 Free Software +Copyright @copyright{} 1990--1995, 1997, 2001--2016 Free Software Foundation, Inc. @sp 1 @@ -1004,11 +1004,11 @@ the name stands for ``Lots of Isolated Silly Parentheses''. But the claim is unwarranted. Lisp stands for LISt Processing, and the programming language handles @emph{lists} (and lists of lists) by putting them between parentheses. The parentheses mark the boundaries -of the list. Sometimes a list is preceded by a single apostrophe or -quotation mark, @samp{'}@footnote{The single apostrophe or quotation -mark is an abbreviation for the function @code{quote}; you need not -think about functions now; functions are defined in @ref{Making -Errors, , Generate an Error Message}.} Lists are the basis of Lisp. +of the list. Sometimes a list is preceded by an apostrophe @samp{'}, +called a @dfn{single-quote} in Lisp.@footnote{A single-quote is an +abbreviation for the special form @code{quote}; you need not think +about special forms now. @xref{Complications}.} Lists are the basis +of Lisp. @menu * Lisp Lists:: What are lists? @@ -2490,14 +2490,7 @@ in the list and then at the function definition bound to that symbol. Then the instructions in the function definition are carried out. @item -A single quotation mark, -@ifinfo -' -@end ifinfo -@ifnotinfo -@code{'} -@end ifnotinfo -, tells the Lisp interpreter that it should +A single-quote @samp{'} tells the Lisp interpreter that it should return the following expression as written, and not evaluate it as it would if the quote were not there. @@ -3454,6 +3447,9 @@ a function. (@xref{Interactive Codes, , Code Characters for Consider the function @code{zap-to-char}. Its interactive expression is +@c FIXME: the interactive expression of zap-to-char has been changed +@c (in 2012-04-10). + @smallexample (interactive "p\ncZap to char: ") @end smallexample @@ -4306,38 +4302,18 @@ documentation, an optional interactive declaration, and the body of the definition. @need 1250 -For example, in an early version of Emacs, the function definition was -as follows. (It is slightly more complex now that it seeks the first -non-whitespace character rather than the first visible character.) +For example, in Emacs the function definition of +@code{dired-unmark-all-marks} is as follows. @smallexample @group -(defun back-to-indentation () - "Move point to first visible character on line." +(defun dired-unmark-all-marks () + "Remove all marks from all files in the Dired buffer." (interactive) - (beginning-of-line 1) - (skip-chars-forward " \t")) + (dired-unmark-all-files ?\r)) @end group @end smallexample -@ignore -In GNU Emacs 22, - -(defun backward-to-indentation (&optional arg) - "Move backward ARG lines and position at first nonblank character." - (interactive "p") - (forward-line (- (or arg 1))) - (skip-chars-forward " \t")) - -(defun back-to-indentation () - "Move point to the first non-whitespace character on this line." - (interactive) - (beginning-of-line 1) - (skip-syntax-forward " " (line-end-position)) - ;; Move back over chars that have whitespace syntax but have the p flag. - (backward-prefix-chars)) -@end ignore - @item interactive Declare to the interpreter that the function can be used interactively. This special form may be followed by a string with one @@ -7627,7 +7603,8 @@ displays in which grave accent and apostrophe were often mirror images suitable for use as quotes. On most modern displays this is no longer true, and when these two ASCII characters appear in documentation strings or diagnostic message formats, Emacs typically transliterates -them to curved single quotes, so that the abovequoted symbol appears +them to @dfn{curved quotes} (left and right single quotation marks), +so that the abovequoted symbol appears as @t{‘case-fold-search’}. Source-code strings can also simply use curved quotes directly. @@ -8678,10 +8655,9 @@ The critical lines are these: @end group @group ;; @r{else} - (push string kill-ring) + (push string kill-ring) @end group @group - (setq kill-ring (cons string kill-ring)) (if (> (length kill-ring) kill-ring-max) ;; @r{avoid overly long kill ring} (setcdr (nthcdr (1- kill-ring-max) kill-ring) nil))) @@ -9072,7 +9048,7 @@ arguments. @item The sixth part is nearly like the argument that follows the @code{interactive} declaration in a function written in Lisp: a letter -followed, perhaps, by a prompt. The only difference from the Lisp is +followed, perhaps, by a prompt. The only difference from Lisp is when the macro is called with no arguments. Then you write a @code{0} (which is a null string), as in this macro. @@ -9112,7 +9088,7 @@ then return an empty string. The @code{del_range_1} function actually deletes the text. It is a complex function we will not look into. It updates the buffer and does other things. However, it is worth looking at the two arguments -passed to @code{del_range}. These are @w{@code{XINT (start)}} and +passed to @code{del_range_1}. These are @w{@code{XINT (start)}} and @w{@code{XINT (end)}}. As far as the C language is concerned, @code{start} and @code{end} are @@ -9121,13 +9097,12 @@ deleted@footnote{More precisely, and requiring more expert knowledge to understand, the two integers are of type @code{Lisp_Object}, which can also be a C union instead of an integer type.}. -In early versions of Emacs, these two numbers were thirty-two bits -long, but the code is slowly being generalized to handle other -lengths. Three of the available bits are used to specify the type of -information; the remaining bits are used as content. +Integer widths depend on the machine, and are typically 32 or 64 bits. +A few of the bits are used to specify the type of information; the +remaining bits are used as content. @samp{XINT} is a C macro that extracts the relevant number from the -longer collection of bits; the three other bits are discarded. +longer collection of bits; the type bits are discarded. @need 800 The command in @code{delete-and-extract-region} looks like this: @@ -11641,7 +11616,7 @@ Else, act on the beginning of the list (the @sc{car} of the list) @end itemize @need 1500 -Here is example: +Here is an example: @smallexample @group @@ -12535,7 +12510,7 @@ value of @code{arg} to 1, in the case when @code{arg} is bound to @code{nil}. Next is a @code{let}. That specifies the values of two local -variables, @code{point} and @code{sentence-end}. The local value of +variables, @code{opoint} and @code{sentence-end}. The local value of point, from before the search, is used in the @code{constrain-to-field} function which handles forms and equivalents. The @code{sentence-end} variable is set by the @@ -14181,7 +14156,7 @@ the expression that moves point forward, word by word. The third part of a recursive function is the recursive call. -Somewhere, also, we also need a part that does the work of the +Somewhere, we also need a part that does the work of the function, a part that does the counting. A vital part! @need 1250 @@ -14479,12 +14454,12 @@ First, write a function to count the words in one definition. This includes the problem of handling symbols as well as words. @item -Second, write a function to list the numbers of words in each function +Second, write a function to list the number of words in each function in a file. This function can use the @code{count-words-in-defun} function. @item -Third, write a function to list the numbers of words in each function +Third, write a function to list the number of words in each function in each of several files. This entails automatically finding the various files, switching to them, and counting the words in the definitions within them. @@ -14949,7 +14924,7 @@ contains two functions, @code{find-file-noselect} and According to its documentation as shown by @kbd{C-h f} (the @code{describe-function} command), the @code{find-file-noselect} function reads the named file into a buffer and returns the buffer. -(Its most recent version includes an optional wildcards argument, +(Its most recent version includes an optional @var{wildcards} argument, too, as well as another to read a file literally and an other you suppress warning messages. These optional arguments are irrelevant.) @@ -15136,7 +15111,7 @@ either a @code{while} loop or recursion. @end ifnottex The design using a @code{while} loop is routine. The argument passed -the function is a list of files. As we saw earlier (@pxref{Loop +to the function is a list of files. As we saw earlier (@pxref{Loop Example}), you can write a @code{while} loop so that the body of the loop is evaluated if such a list contains elements, but to exit the loop if the list is empty. For this design to work, the body of the @@ -16103,7 +16078,7 @@ columns. Very likely, the name of the function will contain either the word ``print'' or the word ``insert'' or the word ``column''. Therefore, we can simply type @kbd{M-x apropos RET print\|insert\|column RET} and look at the result. On my system, this -command once too takes quite some time, and then produced a list of 79 +command once took quite some time, and then produced a list of 79 functions and variables. Now it does not take much time at all and produces a list of 211 functions and variables. Scanning down the list, the only function that looks as if it might do the job is @@ -16180,7 +16155,7 @@ The number of asterisks in the column is the number specified by the current element of the @code{numbers-list}. We need to construct a list of asterisks of the right length for each call to @code{insert-rectangle}. If this list consists solely of the requisite -number of asterisks, then we will have position point the right number +number of asterisks, then we will have to position point the right number of lines above the base for the graph to print correctly. This could be difficult. @@ -16345,7 +16320,7 @@ As written, @code{column-of-graph} contains a major flaw: the symbols used for the blank and for the marked entries in the column are hard-coded as a space and asterisk. This is fine for a prototype, but you, or another user, may wish to use other symbols. For example, -in testing the graph function, you many want to use a period in place +in testing the graph function, you may want to use a period in place of the space, to make sure the point is being repositioned properly each time the @code{insert-rectangle} function is called; or you might want to substitute a @samp{+} sign or other symbol for the asterisk. @@ -16708,7 +16683,7 @@ Write a line graph version of the graph printing functions. ``You don't have to like Emacs to like it''---this seemingly paradoxical statement is the secret of GNU Emacs. The plain, out-of-the-box -Emacs is a generic tool. Most people who use it, customize +Emacs is a generic tool. Most people who use it customize it to suit themselves. GNU Emacs is mostly written in Emacs Lisp; this means that by writing @@ -16904,7 +16879,7 @@ M-x customize @end smallexample @noindent -and find that the group for editing files of data is called ``data''. +and find that the group for editing files of text is called ``Text''. Enter that group. Text Mode Hook is the first member. You can click on its various options, such as @code{turn-on-auto-fill}, to set the values. After you click on the button to @@ -17136,7 +17111,7 @@ This line is a short, but complete Emacs Lisp expression. We are already familiar with @code{setq}. It sets the following variable, @code{major-mode}, to the subsequent value, which is @code{text-mode}. -The single quote mark before @code{text-mode} tells Emacs to deal directly +The single-quote before @code{text-mode} tells Emacs to deal directly with the @code{text-mode} symbol, not with whatever it might stand for. @xref{set & setq, , Setting the Value of a Variable}, for a reminder of how @code{setq} works. @@ -17303,11 +17278,11 @@ Rebinding Keys in Your Init File, emacs, The GNU Emacs Manual}, for details.) The command invoked by the keys is @code{compare-windows}. Note that -@code{compare-windows} is preceded by a single quote; otherwise, Emacs +@code{compare-windows} is preceded by a single-quote; otherwise, Emacs would first try to evaluate the symbol to determine its value. These three things, the double quotation marks, the backslash before -the @samp{C}, and the single quote mark are necessary parts of +the @samp{C}, and the single-quote are necessary parts of keybinding that I tend to forget. Fortunately, I have come to remember that I should look at my existing @file{.emacs} file, and adapt what is there. @@ -18722,10 +18697,7 @@ Even though it is short, @code{split-line} contains expressions we have not studied: @code{skip-chars-forward}, @code{indent-to}, @code{current-column} and @code{insert-and-inherit}. -Consider the @code{skip-chars-forward} function. (It is part of the -function definition for @code{back-to-indentation}, which is shown in -@ref{Review, , Review}.) - +Consider the @code{skip-chars-forward} function. In GNU Emacs, you can find out more about @code{skip-chars-forward} by typing @kbd{C-h f} (@code{describe-function}) and the name of the function. This gives you the function documentation.