Mercurial > emacs
comparison lispintro/emacs-lisp-intro.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | 894ad3892c16 |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 \input texinfo @c -*-texinfo-*- | 1 \input texinfo @c -*-texinfo-*- |
2 @comment %**start of header | 2 @comment %**start of header |
3 @setfilename ../info/eintr | 3 @setfilename ../info/eintr |
4 @c setfilename emacs-lisp-intro.info | |
4 @c sethtmlfilename emacs-lisp-intro.html | 5 @c sethtmlfilename emacs-lisp-intro.html |
5 @settitle Programming in Emacs Lisp | 6 @settitle Programming in Emacs Lisp |
6 @syncodeindex vr cp | 7 @syncodeindex vr cp |
7 @syncodeindex fn cp | 8 @syncodeindex fn cp |
8 @setchapternewpage odd | 9 @setchapternewpage odd |
11 @c --------- | 12 @c --------- |
12 @c <<<< For hard copy printing, this file is now | 13 @c <<<< For hard copy printing, this file is now |
13 @c set for smallbook, which works for all sizes | 14 @c set for smallbook, which works for all sizes |
14 @c of paper, and with Postscript figures >>>> | 15 @c of paper, and with Postscript figures >>>> |
15 @smallbook | 16 @smallbook |
16 @clear largebook | 17 @clear largebook |
17 @set print-postscript-figures | 18 @set print-postscript-figures |
18 @c set largebook | 19 @c set largebook |
19 @c clear print-postscript-figures | 20 @c clear print-postscript-figures |
20 @c --------- | 21 @c --------- |
21 | 22 |
22 @comment %**end of header | 23 @comment %**end of header |
23 | 24 |
24 @set edition-number 2.07 | 25 @set edition-number 2.14 |
25 @set update-date 2002 Aug 23 | 26 @set update-date 2004 Oct 12 |
26 | 27 |
27 @ignore | 28 @ignore |
28 ## Summary of shell commands to create various output formats: | 29 ## Summary of shell commands to create various output formats: |
30 | |
31 pushd /usr/local/src/emacs/lispintro/ | |
29 | 32 |
30 ## Info output | 33 ## Info output |
31 makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi | 34 makeinfo --no-split --paragraph-indent=0 --verbose emacs-lisp-intro.texi |
32 | 35 |
33 ## DVI output | 36 ## DVI output |
45 --verbose emacs-lisp-intro.texi | 48 --verbose emacs-lisp-intro.texi |
46 | 49 |
47 ## XML output | 50 ## XML output |
48 makeinfo --xml --no-split --paragraph-indent=0 \ | 51 makeinfo --xml --no-split --paragraph-indent=0 \ |
49 --verbose emacs-lisp-intro.texi | 52 --verbose emacs-lisp-intro.texi |
53 | |
54 #### (You must be in the same directory as the viewed file.) | |
55 | |
56 ## View DVI output | |
57 xdvi emacs-lisp-intro.dvi & | |
58 | |
59 ## View HTML output | |
60 galeon emacs-lisp-intro.html | |
61 | |
62 ## View Info output with standalone reader | |
63 info emacs-lisp-intro.info | |
64 | |
65 ## popd | |
50 | 66 |
51 @end ignore | 67 @end ignore |
52 | 68 |
53 @c ================ Included Figures ================ | 69 @c ================ Included Figures ================ |
54 | 70 |
142 @end tex | 158 @end tex |
143 @end ifset | 159 @end ifset |
144 | 160 |
145 @c For all sized formats: print within-book cross | 161 @c For all sized formats: print within-book cross |
146 @c reference with ``...'' rather than [...] | 162 @c reference with ``...'' rather than [...] |
163 | |
164 @c This works with the texinfo.tex file, version 2003-05-04.08, | |
165 @c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. | |
166 | |
147 @tex | 167 @tex |
148 % Need following so comma appears after section numbers. | 168 \global\def\xrefprintnodename#1{``#1''} |
149 \global\def\Ysectionnumberandtype{% | |
150 \ifnum\secno=0 \putwordChapter\xreftie\the\chapno, \space % | |
151 \else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno, \space % | |
152 \else \ifnum \subsubsecno=0 % | |
153 \putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno, \space % | |
154 \else % | |
155 \putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno, \space% | |
156 \fi \fi \fi } | |
157 | |
158 \global\def\Yappendixletterandtype{% | |
159 \ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}, \space% | |
160 \else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno, \space % | |
161 \else \ifnum \subsubsecno=0 % | |
162 \putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno, \space % | |
163 \else % | |
164 \putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno, \space % | |
165 \fi \fi \fi } | |
166 | |
167 \global\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup | |
168 \def\printedmanual{\ignorespaces #5}% | |
169 \def\printednodename{\ignorespaces #3}% | |
170 \setbox1=\hbox{\printedmanual}% | |
171 \setbox0=\hbox{\printednodename}% | |
172 \ifdim \wd0 = 0pt | |
173 % No printed node name was explicitly given. | |
174 \ifx\SETxref-automatic-section-title\relax % | |
175 % Use the actual chapter/section title appear inside | |
176 % the square brackets. Use the real section title if we have it. | |
177 \ifdim \wd1>0pt% | |
178 % It is in another manual, so we don't have it. | |
179 \def\printednodename{\ignorespaces #1}% | |
180 \else | |
181 \ifhavexrefs | |
182 % We know the real title if we have the xref values. | |
183 \def\printednodename{\refx{#1-title}}% | |
184 \else | |
185 % Otherwise just copy the Info node name. | |
186 \def\printednodename{\ignorespaces #1}% | |
187 \fi% | |
188 \fi | |
189 \def\printednodename{#1-title}% | |
190 \else | |
191 % Use the node name inside the square brackets. | |
192 \def\printednodename{\ignorespaces #1}% | |
193 \fi | |
194 \fi | |
195 % | |
196 % If we use \unhbox0 and \unhbox1 to print the node names, TeX does not | |
197 % insert empty discretionaries after hyphens, which means that it will | |
198 % not find a line break at a hyphen in a node names. Since some manuals | |
199 % are best written with fairly long node names, containing hyphens, this | |
200 % is a loss. Therefore, we give the text of the node name again, so it | |
201 % is as if TeX is seeing it for the first time. | |
202 \ifdim \wd1 > 0pt | |
203 \putwordsection{} ``\printednodename'' in \cite{\printedmanual}% | |
204 \else | |
205 % _ (for example) has to be the character _ for the purposes of the | |
206 % control sequence corresponding to the node, but it has to expand | |
207 % into the usual \leavevmode...\vrule stuff for purposes of | |
208 % printing. So we \turnoffactive for the \refx-snt, back on for the | |
209 % printing, back off for the \refx-pg. | |
210 {\turnoffactive \refx{#1-snt}{}}% | |
211 % \space [\printednodename],\space % <= original | |
212 % \putwordsection{} ``\printednodename'',\space | |
213 ``\printednodename'',\space | |
214 \turnoffactive \putwordpage\tie\refx{#1-pg}{}% | |
215 \fi | |
216 \endgroup} | |
217 @end tex | 169 @end tex |
218 | 170 |
219 @c ---------------------------------------------------- | 171 @c ---------------------------------------------------- |
220 | 172 |
221 @dircategory Emacs | 173 @dircategory Emacs |
223 * Emacs Lisp Intro: (eintr). | 175 * Emacs Lisp Intro: (eintr). |
224 A simple introduction to Emacs Lisp programming. | 176 A simple introduction to Emacs Lisp programming. |
225 @end direntry | 177 @end direntry |
226 | 178 |
227 @copying | 179 @copying |
228 This is an introduction to @cite{Programming in Emacs Lisp}, for | 180 This is an @cite{Introduction to Programming in Emacs Lisp}, for |
229 people who are not programmers. | 181 people who are not programmers. |
230 | 182 @sp 1 |
231 Edition @value{edition-number}, @value{update-date} | 183 Edition @value{edition-number}, @value{update-date} |
232 | 184 @sp 1 |
233 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc. | 185 Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, |
234 @sp 2 | 186 2002, 2003, 2004, 2005 Free Software Foundation, Inc. |
235 | 187 @sp 1 |
236 Published by the Free Software Foundation, Inc.@* | 188 |
237 59 Temple Place, Suite 330@* | 189 @iftex |
238 Boston, MA 02111-1307 USA@* | 190 Published by the:@* |
239 | 191 |
192 GNU Press, @hfill @uref{http://www.gnupress.org}@* | |
193 a division of the @hfill General: @email{press@@gnu.org}@* | |
194 Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@* | |
195 51 Franklin Street, Fifth Floor @hfill Tel: +1 (617) 542-5942@* | |
196 Boston, MA 02110-1301 USA @hfill Fax: +1 (617) 542-2652@* | |
197 @end iftex | |
198 | |
199 @ifnottex | |
200 Published by the: | |
201 | |
202 @example | |
203 GNU Press, Website: http://www.gnupress.org | |
204 a division of the General: press@@gnu.org | |
205 Free Software Foundation, Inc. Orders: sales@@gnu.org | |
206 51 Franklin Street, Fifth Floor Tel: +1 (617) 542-5942 | |
207 Boston, MA 02110-1301 USA Fax: +1 (617) 542-2652 | |
208 @end example | |
209 @end ifnottex | |
210 | |
211 @sp 1 | |
240 @c Printed copies are available for $30 each.@* | 212 @c Printed copies are available for $30 each.@* |
241 ISBN 1-882114-43-4 | 213 ISBN 1-882114-43-4 |
242 | 214 |
243 Permission is granted to copy, distribute and/or modify this document | 215 Permission is granted to copy, distribute and/or modify this document |
244 under the terms of the GNU Free Documentation License, Version 1.1 or | 216 under the terms of the GNU Free Documentation License, Version 1.2 or |
245 any later version published by the Free Software Foundation; there | 217 any later version published by the Free Software Foundation; there |
246 being no Invariant Section, with the Front-Cover Texts being ``A GNU | 218 being no Invariant Section, with the Front-Cover Texts being ``A GNU |
247 Manual'', and with the Back-Cover Texts as in (a) below. A copy of | 219 Manual'', and with the Back-Cover Texts as in (a) below. A copy of |
248 the license is included in the section entitled ``GNU Free | 220 the license is included in the section entitled ``GNU Free |
249 Documentation License''. | 221 Documentation License''. |
267 @sp 6 | 239 @sp 6 |
268 @center @titlefont{An Introduction to} | 240 @center @titlefont{An Introduction to} |
269 @sp 2 | 241 @sp 2 |
270 @center @titlefont{Programming in Emacs Lisp} | 242 @center @titlefont{Programming in Emacs Lisp} |
271 @sp 2 | 243 @sp 2 |
272 @center Second Edition | 244 @center Revised Second Edition |
273 @sp 4 | 245 @sp 4 |
274 @center by Robert J. Chassell | 246 @center by Robert J. Chassell |
275 | 247 |
276 @page | 248 @page |
277 @vskip 0pt plus 1filll | 249 @vskip 0pt plus 1filll |
283 @evenheading @thispage @| @| @thischapter | 255 @evenheading @thispage @| @| @thischapter |
284 @oddheading @thissection @| @| @thispage | 256 @oddheading @thissection @| @| @thispage |
285 @end iftex | 257 @end iftex |
286 | 258 |
287 @ifnothtml | 259 @ifnothtml |
288 | 260 @c Keep T.O.C. short by tightening up for largebook |
289 @c Keep T.O.C. short by tightening up. | |
290 @ifset largebook | 261 @ifset largebook |
291 @tex | 262 @tex |
292 \global\parskip 2pt plus 1pt | 263 \global\parskip 2pt plus 1pt |
293 \global\advance\baselineskip by -1pt | 264 \global\advance\baselineskip by -1pt |
294 @end tex | 265 @end tex |
295 @end ifset | 266 @end ifset |
267 @end ifnothtml | |
296 | 268 |
297 @shortcontents | 269 @shortcontents |
298 @contents | 270 @contents |
299 | |
300 @ifset largebook | |
301 @tex | |
302 \global\parskip 6pt plus 1pt | |
303 \global\advance\baselineskip by 1pt | |
304 @end tex | |
305 @end ifset | |
306 | |
307 @end ifnothtml | |
308 | |
309 @c >>>> Set pageno appropriately <<<< | |
310 | |
311 @c The first page of the Preface is a roman numeral; it is the first | |
312 @c right handed page after the Table of Contents; hence the following | |
313 @c setting must be for an odd negative number. | |
314 | |
315 @c if largebook, there are 8 pages in Table of Contents | |
316 @ifset largebook | |
317 @iftex | |
318 @pageno = -9 | |
319 @end iftex | |
320 @end ifset | |
321 | |
322 @c if smallbook, there are 10 pages in Table of Contents | |
323 @ifclear largebook | |
324 @iftex | |
325 @pageno = -11 | |
326 @end iftex | |
327 @end ifclear | |
328 | 271 |
329 @ifnottex | 272 @ifnottex |
330 @node Top, Preface, (dir), (dir) | 273 @node Top, Preface, (dir), (dir) |
331 @top An Introduction to Programming in Emacs Lisp | 274 @top An Introduction to Programming in Emacs Lisp |
332 | 275 |
358 * Debugging:: How to run the Emacs Lisp debuggers. | 301 * Debugging:: How to run the Emacs Lisp debuggers. |
359 * Conclusion:: Now you have the basics. | 302 * Conclusion:: Now you have the basics. |
360 * the-the:: An appendix: how to find reduplicated words. | 303 * the-the:: An appendix: how to find reduplicated words. |
361 * Kill Ring:: An appendix: how the kill ring works. | 304 * Kill Ring:: An appendix: how the kill ring works. |
362 * Full Graph:: How to create a graph with labelled axes. | 305 * Full Graph:: How to create a graph with labelled axes. |
306 * Free Software and Free Manuals:: | |
363 * GNU Free Documentation License:: | 307 * GNU Free Documentation License:: |
364 * Index:: | 308 * Index:: |
365 * About the Author:: | 309 * About the Author:: |
366 | 310 |
367 @detailmenu | 311 @detailmenu |
777 Handling the Kill Ring | 721 Handling the Kill Ring |
778 | 722 |
779 * rotate-yank-pointer:: Move a pointer along a list and around. | 723 * rotate-yank-pointer:: Move a pointer along a list and around. |
780 * yank:: Paste a copy of a clipped element. | 724 * yank:: Paste a copy of a clipped element. |
781 * yank-pop:: Insert first element pointed to. | 725 * yank-pop:: Insert first element pointed to. |
726 * ring file:: | |
782 | 727 |
783 The @code{rotate-yank-pointer} Function | 728 The @code{rotate-yank-pointer} Function |
784 | 729 |
785 * Understanding rotate-yk-ptr:: | 730 * Understanding rotate-yk-ptr:: |
786 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}. | 731 * rotate-yk-ptr body:: The body of @code{rotate-yank-pointer}. |
829 * Another Bug:: Yet another bug @dots{} most insidious. | 774 * Another Bug:: Yet another bug @dots{} most insidious. |
830 * Final printed graph:: The graph itself! | 775 * Final printed graph:: The graph itself! |
831 | 776 |
832 @end detailmenu | 777 @end detailmenu |
833 @end menu | 778 @end menu |
779 | |
780 @c >>>> Set pageno appropriately <<<< | |
781 | |
782 @c The first page of the Preface is a roman numeral; it is the first | |
783 @c right handed page after the Table of Contents; hence the following | |
784 @c setting must be for an odd negative number. | |
785 | |
786 @iftex | |
787 @global@pageno = -11 | |
788 @end iftex | |
834 | 789 |
835 @node Preface, List Processing, Top, Top | 790 @node Preface, List Processing, Top, Top |
836 @comment node-name, next, previous, up | 791 @comment node-name, next, previous, up |
837 @unnumbered Preface | 792 @unnumbered Preface |
838 | 793 |
1088 | 1043 |
1089 @iftex | 1044 @iftex |
1090 @headings off | 1045 @headings off |
1091 @evenheading @thispage @| @| @thischapter | 1046 @evenheading @thispage @| @| @thischapter |
1092 @oddheading @thissection @| @| @thispage | 1047 @oddheading @thissection @| @| @thispage |
1093 @pageno = 1 | 1048 @global@pageno = 1 |
1094 @end iftex | 1049 @end iftex |
1095 | 1050 |
1096 @node List Processing, Practicing Evaluation, Preface, Top | 1051 @node List Processing, Practicing Evaluation, Preface, Top |
1097 @comment node-name, next, previous, up | 1052 @comment node-name, next, previous, up |
1098 @chapter List Processing | 1053 @chapter List Processing |
1099 | 1054 |
1100 To the untutored eye, Lisp is a strange programming language. In Lisp | 1055 To the untutored eye, Lisp is a strange programming language. In Lisp |
1101 code there are parentheses everywhere. Some people even claim that the | 1056 code there are parentheses everywhere. Some people even claim that |
1102 name stands for `Lots of Isolated Silly Parentheses'. But the claim is | 1057 the name stands for `Lots of Isolated Silly Parentheses'. But the |
1103 unwarranted. Lisp stands for LISt Processing, and the programming | 1058 claim is unwarranted. Lisp stands for LISt Processing, and the |
1104 language handles @emph{lists} (and lists of lists) by putting them | 1059 programming language handles @emph{lists} (and lists of lists) by |
1105 between parentheses. The parentheses mark the boundaries of the list. | 1060 putting them between parentheses. The parentheses mark the boundaries |
1106 Sometimes a list is preceded by a single apostrophe or quotation mark, | 1061 of the list. Sometimes a list is preceded by a single apostrophe or |
1107 @samp{'}. Lists are the basis of Lisp. | 1062 quotation mark, @samp{'}@footnote{The single apostrophe or quotation |
1063 mark is an abbreviation for the function @code{quote}; you need not | |
1064 think about functions now; functions are defined in @ref{Making | |
1065 Errors, , Generate an Error Message}.} Lists are the basis of Lisp. | |
1108 | 1066 |
1109 @menu | 1067 @menu |
1110 * Lisp Lists:: What are lists? | 1068 * Lisp Lists:: What are lists? |
1111 * Run a Program:: Any list in Lisp is a program ready to run. | 1069 * Run a Program:: Any list in Lisp is a program ready to run. |
1112 * Making Errors:: Generating an error message. | 1070 * Making Errors:: Generating an error message. |
1540 @code{+}, is not itself the set of instructions for the computer to | 1498 @code{+}, is not itself the set of instructions for the computer to |
1541 carry out. Instead, the symbol is used, perhaps temporarily, as a way | 1499 carry out. Instead, the symbol is used, perhaps temporarily, as a way |
1542 of locating the definition or set of instructions. What we see is the | 1500 of locating the definition or set of instructions. What we see is the |
1543 name through which the instructions can be found. Names of people | 1501 name through which the instructions can be found. Names of people |
1544 work the same way. I can be referred to as @samp{Bob}; however, I am | 1502 work the same way. I can be referred to as @samp{Bob}; however, I am |
1545 not the letters @samp{B}, @samp{o}, @samp{b} but am the consciousness | 1503 not the letters @samp{B}, @samp{o}, @samp{b} but am, or were, the |
1546 consistently associated with a particular life-form. The name is not | 1504 consciousness consistently associated with a particular life-form. |
1547 me, but it can be used to refer to me. | 1505 The name is not me, but it can be used to refer to me. |
1548 | 1506 |
1549 In Lisp, one set of instructions can be attached to several names. | 1507 In Lisp, one set of instructions can be attached to several names. |
1550 For example, the computer instructions for adding numbers can be | 1508 For example, the computer instructions for adding numbers can be |
1551 linked to the symbol @code{plus} as well as to the symbol @code{+} | 1509 linked to the symbol @code{plus} as well as to the symbol @code{+} |
1552 (and are in some dialects of Lisp). Among humans, I can be referred | 1510 (and are in some dialects of Lisp). Among humans, I can be referred |
2006 The type of data that should be passed to a function depends on what | 1964 The type of data that should be passed to a function depends on what |
2007 kind of information it uses. The arguments to a function such as | 1965 kind of information it uses. The arguments to a function such as |
2008 @code{+} must have values that are numbers, since @code{+} adds numbers. | 1966 @code{+} must have values that are numbers, since @code{+} adds numbers. |
2009 Other functions use different kinds of data for their arguments. | 1967 Other functions use different kinds of data for their arguments. |
2010 | 1968 |
1969 @need 1250 | |
2011 @findex concat | 1970 @findex concat |
2012 For example, the @code{concat} function links together or unites two or | 1971 For example, the @code{concat} function links together or unites two or |
2013 more strings of text to produce a string. The arguments are strings. | 1972 more strings of text to produce a string. The arguments are strings. |
2014 Concatenating the two character strings @code{abc}, @code{def} produces | 1973 Concatenating the two character strings @code{abc}, @code{def} produces |
2015 the single string @code{abcdef}. This can be seen by evaluating the | 1974 the single string @code{abcdef}. This can be seen by evaluating the |
2180 @end group | 2139 @end group |
2181 @end smallexample | 2140 @end smallexample |
2182 | 2141 |
2183 @need 1250 | 2142 @need 1250 |
2184 As usual, the error message tries to be helpful and makes sense after you | 2143 As usual, the error message tries to be helpful and makes sense after you |
2185 learn how to read it. | 2144 learn how to read it.@footnote{@code{(quote hello)} is an expansion of |
2145 the abbreviation @code{'hello}.} | |
2186 | 2146 |
2187 The first part of the error message is straightforward; it says | 2147 The first part of the error message is straightforward; it says |
2188 @samp{wrong type argument}. Next comes the mysterious jargon word | 2148 @samp{wrong type argument}. Next comes the mysterious jargon word |
2189 @w{@samp{number-or-marker-p}}. This word is trying to tell you what | 2149 @w{@samp{number-or-marker-p}}. This word is trying to tell you what |
2190 kind of argument the @code{+} expected. | 2150 kind of argument the @code{+} expected. |
2322 for @samp{%s}: | 2282 for @samp{%s}: |
2323 | 2283 |
2324 @smallexample | 2284 @smallexample |
2325 @group | 2285 @group |
2326 (message "He saw %d %s" | 2286 (message "He saw %d %s" |
2327 (- fill-column 34) | 2287 (- fill-column 32) |
2328 (concat "red " | 2288 (concat "red " |
2329 (substring | 2289 (substring |
2330 "The quick brown foxes jumped." 16 21) | 2290 "The quick brown foxes jumped." 16 21) |
2331 " leaping.")) | 2291 " leaping.")) |
2332 @end group | 2292 @end group |
2534 | 2494 |
2535 Learning Lisp is like climbing a hill in which the first part is the | 2495 Learning Lisp is like climbing a hill in which the first part is the |
2536 steepest. You have now climbed the most difficult part; what remains | 2496 steepest. You have now climbed the most difficult part; what remains |
2537 becomes easier as you progress onwards. | 2497 becomes easier as you progress onwards. |
2538 | 2498 |
2499 @need 1000 | |
2539 In summary, | 2500 In summary, |
2540 | 2501 |
2541 @itemize @bullet | 2502 @itemize @bullet |
2542 | 2503 |
2543 @item | 2504 @item |
3533 each argument by adding parts to the string that follows | 3494 each argument by adding parts to the string that follows |
3534 @code{interactive}. When you do this, the information is passed to | 3495 @code{interactive}. When you do this, the information is passed to |
3535 each argument in the same order it is specified in the | 3496 each argument in the same order it is specified in the |
3536 @code{interactive} list. In the string, each part is separated from | 3497 @code{interactive} list. In the string, each part is separated from |
3537 the next part by a @samp{\n}, which is a newline. For example, you | 3498 the next part by a @samp{\n}, which is a newline. For example, you |
3538 could follow @code{"BAppend to buffer:@: "} with a @samp{\n}) and an | 3499 could follow @code{"BAppend to buffer:@: "} with a @samp{\n} and an |
3539 @samp{r}. This would cause Emacs to pass the values of point and mark | 3500 @samp{r}. This would cause Emacs to pass the values of point and mark |
3540 to the function as well as prompt you for the buffer---three arguments | 3501 to the function as well as prompt you for the buffer---three arguments |
3541 in all. | 3502 in all. |
3542 | 3503 |
3543 In this case, the function definition would look like the following, | 3504 In this case, the function definition would look like the following, |
3565 @code{(interactive)}. The @code{mark-whole-buffer} function is like | 3526 @code{(interactive)}. The @code{mark-whole-buffer} function is like |
3566 this. | 3527 this. |
3567 | 3528 |
3568 Alternatively, if the special letter-codes are not right for your | 3529 Alternatively, if the special letter-codes are not right for your |
3569 application, you can pass your own arguments to @code{interactive} as | 3530 application, you can pass your own arguments to @code{interactive} as |
3570 a list. @xref{interactive, , Using @code{Interactive}, elisp, The | 3531 a list. @xref{Using Interactive, , Using @code{Interactive}, elisp, The |
3571 GNU Emacs Lisp Reference Manual}, for more information about this advanced | 3532 GNU Emacs Lisp Reference Manual}, for more information about this advanced |
3572 technique. | 3533 technique. |
3573 | 3534 |
3574 @node Permanent Installation, let, Interactive Options, Writing Defuns | 3535 @node Permanent Installation, let, Interactive Options, Writing Defuns |
3575 @comment node-name, next, previous, up | 3536 @comment node-name, next, previous, up |
4046 An @code{if} expression may have an optional third argument, called | 4007 An @code{if} expression may have an optional third argument, called |
4047 the @dfn{else-part}, for the case when the true-or-false-test returns | 4008 the @dfn{else-part}, for the case when the true-or-false-test returns |
4048 false. When this happens, the second argument or then-part of the | 4009 false. When this happens, the second argument or then-part of the |
4049 overall @code{if} expression is @emph{not} evaluated, but the third or | 4010 overall @code{if} expression is @emph{not} evaluated, but the third or |
4050 else-part @emph{is} evaluated. You might think of this as the cloudy | 4011 else-part @emph{is} evaluated. You might think of this as the cloudy |
4051 day alternative for the decision `if it is warm and sunny, then go to | 4012 day alternative for the decision ``if it is warm and sunny, then go to |
4052 the beach, else read a book!''. | 4013 the beach, else read a book!''. |
4053 | 4014 |
4054 The word ``else'' is not written in the Lisp code; the else-part of an | 4015 The word ``else'' is not written in the Lisp code; the else-part of an |
4055 @code{if} expression comes after the then-part. In the written Lisp, the | 4016 @code{if} expression comes after the then-part. In the written Lisp, the |
4056 else-part is usually written to start on a line of its own and is | 4017 else-part is usually written to start on a line of its own and is |
4390 or more parts that pass the information to the arguments of the | 4351 or more parts that pass the information to the arguments of the |
4391 function, in sequence. These parts may also tell the interpreter to | 4352 function, in sequence. These parts may also tell the interpreter to |
4392 prompt for information. Parts of the string are separated by | 4353 prompt for information. Parts of the string are separated by |
4393 newlines, @samp{\n}. | 4354 newlines, @samp{\n}. |
4394 | 4355 |
4356 @need 1000 | |
4395 Common code characters are: | 4357 Common code characters are: |
4396 | 4358 |
4397 @table @code | 4359 @table @code |
4398 @item b | 4360 @item b |
4399 The name of an existing buffer. | 4361 The name of an existing buffer. |
4520 @item message | 4482 @item message |
4521 Print a message in the echo area. The first argument is a string that | 4483 Print a message in the echo area. The first argument is a string that |
4522 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of | 4484 can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of |
4523 arguments that follow the string. The argument used by @samp{%s} must | 4485 arguments that follow the string. The argument used by @samp{%s} must |
4524 be a string or a symbol; the argument used by @samp{%d} must be a | 4486 be a string or a symbol; the argument used by @samp{%d} must be a |
4525 number. The argument used by @samp{%c} must be an ascii code number; | 4487 number. The argument used by @samp{%c} must be an @sc{ascii} code |
4526 it will be printed as the character with that @sc{ascii} code. | 4488 number; it will be printed as the character with that @sc{ascii} code. |
4527 | 4489 |
4528 @item setq | 4490 @item setq |
4529 @itemx set | 4491 @itemx set |
4530 The @code{setq} function sets the value of its first argument to the | 4492 The @code{setq} function sets the value of its first argument to the |
4531 value of the second argument. The first argument is automatically | 4493 value of the second argument. The first argument is automatically |
4629 | 4591 |
4630 @cindex Find source of function | 4592 @cindex Find source of function |
4631 In versions 20 and higher, when a function is written in Emacs Lisp, | 4593 In versions 20 and higher, when a function is written in Emacs Lisp, |
4632 @code{describe-function} will also tell you the location of the | 4594 @code{describe-function} will also tell you the location of the |
4633 function definition. If you move point over the file name and press | 4595 function definition. If you move point over the file name and press |
4634 the @key{RET} key, which is this case means @code{help-follow} rather | 4596 the @key{RET} key, which in this case means @code{help-follow} rather |
4635 than `return' or `enter', Emacs will take you directly to the function | 4597 than `return' or `enter', Emacs will take you directly to the function |
4636 definition. | 4598 definition. |
4637 | 4599 |
4638 More generally, if you want to see a function in its original source | 4600 More generally, if you want to see a function in its original source |
4639 file, you can use the @code{find-tags} function to jump to it. | 4601 file, you can use the @code{find-tags} function to jump to it. |
4644 | 4606 |
4645 The @code{find-tags} function depends on `tags tables' that record | 4607 The @code{find-tags} function depends on `tags tables' that record |
4646 the locations of the functions, variables, and other items to which | 4608 the locations of the functions, variables, and other items to which |
4647 @code{find-tags} jumps. | 4609 @code{find-tags} jumps. |
4648 | 4610 |
4649 To use the @code{find-tags} command, type @kbd{M-.} (i.e., type the | 4611 To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the |
4650 @key{META} key and the period key at the same time, or else type the | 4612 period key while holding down the @key{META} key, or else type the |
4651 @key{ESC} key and then type the period key), and then, at the prompt, | 4613 @key{ESC} key and then type the period key), and then, at the prompt, |
4652 type in the name of the function whose source code you want to see, | 4614 type in the name of the function whose source code you want to see, |
4653 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will | 4615 such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will |
4654 switch buffers and display the source code for the function on your | 4616 switch buffers and display the source code for the function on your |
4655 screen. To switch back to your current buffer, type @kbd{C-x b | 4617 screen. To switch back to your current buffer, type @kbd{C-x b |
4665 interested in Emacs sources, the tags table you will most likely want, | 4627 interested in Emacs sources, the tags table you will most likely want, |
4666 if it has already been created for you, will be in a subdirectory of | 4628 if it has already been created for you, will be in a subdirectory of |
4667 the @file{/usr/local/share/emacs/} directory; thus you would use the | 4629 the @file{/usr/local/share/emacs/} directory; thus you would use the |
4668 @code{M-x visit-tags-table} command and specify a pathname such as | 4630 @code{M-x visit-tags-table} command and specify a pathname such as |
4669 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or | 4631 @file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or |
4670 @file{/usr/local/src/emacs/lisp/TAGS}. If the tags table has | 4632 @file{/usr/local/src/emacs/src/TAGS}. If the tags table has |
4671 not already been created, you will have to create it yourself. | 4633 not already been created, you will have to create it yourself. |
4672 | 4634 |
4673 @need 1250 | 4635 @need 1250 |
4674 To create a @file{TAGS} file in a specific directory, switch to that | 4636 To create a @file{TAGS} file in a specific directory, switch to that |
4675 directory in Emacs using @kbd{M-x cd} command, or list the directory | 4637 directory in Emacs using @kbd{M-x cd} command, or list the directory |
4890 The next line is an @code{(interactive)} expression that tells Emacs | 4852 The next line is an @code{(interactive)} expression that tells Emacs |
4891 that the function will be used interactively. These details are similar | 4853 that the function will be used interactively. These details are similar |
4892 to the @code{simplified-beginning-of-buffer} function described in the | 4854 to the @code{simplified-beginning-of-buffer} function described in the |
4893 previous section. | 4855 previous section. |
4894 | 4856 |
4857 @need 1250 | |
4895 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer | 4858 @node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer |
4896 @comment node-name, next, previous, up | 4859 @comment node-name, next, previous, up |
4897 @subsection Body of @code{mark-whole-buffer} | 4860 @subsection Body of @code{mark-whole-buffer} |
4898 | 4861 |
4899 The body of the @code{mark-whole-buffer} function consists of three | 4862 The body of the @code{mark-whole-buffer} function consists of three |
5474 @code{insert-buffer} is yet another buffer-related function. This | 5437 @code{insert-buffer} is yet another buffer-related function. This |
5475 command copies another buffer @emph{into} the current buffer. It is the | 5438 command copies another buffer @emph{into} the current buffer. It is the |
5476 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they | 5439 reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they |
5477 copy a region of text @emph{from} the current buffer to another buffer. | 5440 copy a region of text @emph{from} the current buffer to another buffer. |
5478 | 5441 |
5442 Here is a discussion based on the original code. The code was | |
5443 simplified in 2003 and is harder to understand. | |
5444 | |
5479 In addition, this code illustrates the use of @code{interactive} with a | 5445 In addition, this code illustrates the use of @code{interactive} with a |
5480 buffer that might be @dfn{read-only} and the important distinction | 5446 buffer that might be @dfn{read-only} and the important distinction |
5481 between the name of an object and the object actually referred to. | 5447 between the name of an object and the object actually referred to. |
5482 | 5448 |
5483 @menu | 5449 @menu |
5679 and false if its argument is true. So if @code{(bufferp buffer)} | 5645 and false if its argument is true. So if @code{(bufferp buffer)} |
5680 returns true, the @code{not} expression returns false and vice-versa: | 5646 returns true, the @code{not} expression returns false and vice-versa: |
5681 what is ``not true'' is false and what is ``not false'' is true. | 5647 what is ``not true'' is false and what is ``not false'' is true. |
5682 | 5648 |
5683 Using this test, the @code{if} expression works as follows: when the | 5649 Using this test, the @code{if} expression works as follows: when the |
5684 value of the variable @code{buffer} is actually a buffer rather then | 5650 value of the variable @code{buffer} is actually a buffer rather than |
5685 its name, the true-or-false-test returns false and the @code{if} | 5651 its name, the true-or-false-test returns false and the @code{if} |
5686 expression does not evaluate the then-part. This is fine, since we do | 5652 expression does not evaluate the then-part. This is fine, since we do |
5687 not need to do anything to the variable @code{buffer} if it really is | 5653 not need to do anything to the variable @code{buffer} if it really is |
5688 a buffer. | 5654 a buffer. |
5689 | 5655 |
5827 the @code{let} expression, the @code{(push-mark newmark)} expression | 5793 the @code{let} expression, the @code{(push-mark newmark)} expression |
5828 function sets a mark to this location. (The previous location of the | 5794 function sets a mark to this location. (The previous location of the |
5829 mark is still accessible; it is recorded on the mark ring and you can | 5795 mark is still accessible; it is recorded on the mark ring and you can |
5830 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is | 5796 go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is |
5831 located at the beginning of the inserted text, which is where it was | 5797 located at the beginning of the inserted text, which is where it was |
5832 before you called the insert function. | 5798 before you called the insert function, the position of which was saved |
5799 by the first @code{save-excursion}. | |
5833 | 5800 |
5834 @need 1250 | 5801 @need 1250 |
5835 The whole @code{let} expression looks like this: | 5802 The whole @code{let} expression looks like this: |
5836 | 5803 |
5837 @smallexample | 5804 @smallexample |
6128 @code{(prefix-numeric-value arg)}, which converts the raw argument to a | 6095 @code{(prefix-numeric-value arg)}, which converts the raw argument to a |
6129 number. This number is multiplied by the buffer size in the following | 6096 number. This number is multiplied by the buffer size in the following |
6130 expression: | 6097 expression: |
6131 | 6098 |
6132 @smallexample | 6099 @smallexample |
6133 (* (buffer-size) (prefix-numeric-value arg) | 6100 (* (buffer-size) (prefix-numeric-value arg)) |
6134 @end smallexample | 6101 @end smallexample |
6135 | 6102 |
6136 @noindent | 6103 @noindent |
6137 This multiplication creates a number that may be larger than the size of | 6104 This multiplication creates a number that may be larger than the size of |
6138 the buffer---seven times larger if the argument is 7, for example. Ten | 6105 the buffer---seven times larger if the argument is 7, for example. Ten |
6141 position in the buffer. | 6108 position in the buffer. |
6142 | 6109 |
6143 The number that results from all this is passed to @code{goto-char} and | 6110 The number that results from all this is passed to @code{goto-char} and |
6144 the cursor is moved to that point. | 6111 the cursor is moved to that point. |
6145 | 6112 |
6113 @need 1500 | |
6146 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer | 6114 @node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer |
6147 @comment node-name, next, previous, up | 6115 @comment node-name, next, previous, up |
6148 @subsection The Complete @code{beginning-of-buffer} | 6116 @subsection The Complete @code{beginning-of-buffer} |
6149 | 6117 |
6150 @need 800 | 6118 @need 1000 |
6151 Here is the complete text of the @code{beginning-of-buffer} function: | 6119 Here is the complete text of the @code{beginning-of-buffer} function: |
6120 @sp 1 | |
6152 | 6121 |
6153 @smallexample | 6122 @smallexample |
6154 @group | 6123 @group |
6155 (defun beginning-of-buffer (&optional arg) | 6124 (defun beginning-of-buffer (&optional arg) |
6156 "Move point to the beginning of the buffer; | 6125 "Move point to the beginning of the buffer; |
6157 leave mark at previous position. | 6126 leave mark at previous position. |
6158 With arg N, put point N/10 of the way | 6127 With arg N, put point N/10 of the way |
6159 from the true beginning. | 6128 from the true beginning. |
6129 @end group | |
6130 @group | |
6160 Don't use this in Lisp programs! | 6131 Don't use this in Lisp programs! |
6161 \(goto-char (point-min)) is faster | 6132 \(goto-char (point-min)) is faster |
6162 and does not set the mark." | 6133 and does not set the mark." |
6163 (interactive "P") | 6134 (interactive "P") |
6164 (push-mark) | 6135 (push-mark) |
6262 | 6233 |
6263 @node optional Exercise, , Second Buffer Related Review, More Complex | 6234 @node optional Exercise, , Second Buffer Related Review, More Complex |
6264 @section @code{optional} Argument Exercise | 6235 @section @code{optional} Argument Exercise |
6265 | 6236 |
6266 Write an interactive function with an optional argument that tests | 6237 Write an interactive function with an optional argument that tests |
6267 whether its argument, a number, is greater or less than the value of | 6238 whether its argument, a number, is greater than or equal to, or else, |
6268 @code{fill-column}, and tells you which, in a message. However, if you | 6239 less than the value of @code{fill-column}, and tells you which, in a |
6269 do not pass an argument to the function, use 56 as a default value. | 6240 message. However, if you do not pass an argument to the function, use |
6241 56 as a default value. | |
6270 | 6242 |
6271 @node Narrowing & Widening, car cdr & cons, More Complex, Top | 6243 @node Narrowing & Widening, car cdr & cons, More Complex, Top |
6272 @comment node-name, next, previous, up | 6244 @comment node-name, next, previous, up |
6273 @chapter Narrowing and Widening | 6245 @chapter Narrowing and Widening |
6274 @cindex Focusing attention (narrowing) | 6246 @cindex Focusing attention (narrowing) |
6393 @cindex Widening, example of | 6365 @cindex Widening, example of |
6394 | 6366 |
6395 The @code{what-line} command tells you the number of the line in which | 6367 The @code{what-line} command tells you the number of the line in which |
6396 the cursor is located. The function illustrates the use of the | 6368 the cursor is located. The function illustrates the use of the |
6397 @code{save-restriction} and @code{save-excursion} commands. Here is the | 6369 @code{save-restriction} and @code{save-excursion} commands. Here is the |
6398 text of the function in full: | 6370 original text of the function: |
6399 | 6371 |
6400 @smallexample | 6372 @smallexample |
6401 @group | 6373 @group |
6402 (defun what-line () | 6374 (defun what-line () |
6403 "Print the current line number (in the buffer) of point." | 6375 "Print the current line number (in the buffer) of point." |
6409 (message "Line %d" | 6381 (message "Line %d" |
6410 (1+ (count-lines 1 (point))))))) | 6382 (1+ (count-lines 1 (point))))))) |
6411 @end group | 6383 @end group |
6412 @end smallexample | 6384 @end smallexample |
6413 | 6385 |
6414 The function has a documentation line and is interactive, as you would | 6386 (In recent versions of GNU Emacs, the @code{what-line} function has |
6415 expect. The next two lines use the functions @code{save-restriction} and | 6387 been expanded to tell you your line number in a narrowed buffer as |
6416 @code{widen}. | 6388 well as your line number in a widened buffer. The recent version is |
6389 more complex than the version shown here. If you feel adventurous, | |
6390 you might want to look at it after figuring out how this version | |
6391 works. The newer version uses a conditional to determine whether the | |
6392 buffer has been narrowed, and rather than use @code{beginning-of-line} | |
6393 to move point to the beginning of the current line, if need be, the | |
6394 function uses @code{(forward-line 0)}.) | |
6395 | |
6396 The function as shown here has a documentation line and is | |
6397 interactive, as you would expect. The next two lines use the | |
6398 functions @code{save-restriction} and @code{widen}. | |
6417 | 6399 |
6418 The @code{save-restriction} special form notes whatever narrowing is in | 6400 The @code{save-restriction} special form notes whatever narrowing is in |
6419 effect, if any, in the current buffer and restores that narrowing after | 6401 effect, if any, in the current buffer and restores that narrowing after |
6420 the code in the body of the @code{save-restriction} has been evaluated. | 6402 the code in the body of the @code{save-restriction} has been evaluated. |
6421 | 6403 |
6457 @samp{%s}, or @samp{%c} to print arguments that follow the string. | 6439 @samp{%s}, or @samp{%c} to print arguments that follow the string. |
6458 @samp{%d} prints the argument as a decimal, so the message will say | 6440 @samp{%d} prints the argument as a decimal, so the message will say |
6459 something such as @samp{Line 243}. | 6441 something such as @samp{Line 243}. |
6460 | 6442 |
6461 @need 1200 | 6443 @need 1200 |
6444 | |
6462 The number that is printed in place of the @samp{%d} is computed by the | 6445 The number that is printed in place of the @samp{%d} is computed by the |
6463 last line of the function: | 6446 last line of the function: |
6464 | 6447 |
6465 @smallexample | 6448 @smallexample |
6466 (1+ (count-lines 1 (point))) | 6449 (1+ (count-lines 1 (point))) |
6482 @node narrow Exercise, , what-line, Narrowing & Widening | 6465 @node narrow Exercise, , what-line, Narrowing & Widening |
6483 @section Exercise with Narrowing | 6466 @section Exercise with Narrowing |
6484 | 6467 |
6485 Write a function that will display the first 60 characters of the | 6468 Write a function that will display the first 60 characters of the |
6486 current buffer, even if you have narrowed the buffer to its latter | 6469 current buffer, even if you have narrowed the buffer to its latter |
6487 half so that the first line is inaccessible. Restore point, mark, | 6470 half so that the first line is inaccessible. Restore point, mark, and |
6488 and narrowing. For this exercise, you need to use | 6471 narrowing. For this exercise, you need to use a whole potpourri of |
6489 @code{save-restriction}, @code{widen}, @code{goto-char}, | 6472 functions, including @code{save-restriction}, @code{widen}, |
6490 @code{point-min}, @code{buffer-substring}, @code{message}, and other | 6473 @code{goto-char}, @code{point-min}, @code{message}, and |
6491 functions, a whole potpourri. | 6474 @code{buffer-substring}. |
6475 | |
6476 @cindex Properties, mention of @code{buffer-substring-no-properties} | |
6477 (@code{buffer-substring} is a previously unmentioned function you will | |
6478 have to investigate yourself; or perhaps you will have to use | |
6479 @code{buffer-substring-no-properties} @dots{}, yet another function | |
6480 and one that introduces text properties, a feature otherwise not | |
6481 discussed here. @xref{Text Properties, , Text Properties, elisp, The | |
6482 GNU Emacs Lisp Reference Manual}. Additionally, do you really need | |
6483 @code{goto-char} or @code{point-min}? Or can you write the function | |
6484 without them?) | |
6492 | 6485 |
6493 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top | 6486 @node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top |
6494 @comment node-name, next, previous, up | 6487 @comment node-name, next, previous, up |
6495 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions | 6488 @chapter @code{car}, @code{cdr}, @code{cons}: Fundamental Functions |
6496 @findex car, @r{introduced} | 6489 @findex car, @r{introduced} |
6568 first item. Thus, while the @sc{car} of the list @code{'(rose violet | 6561 first item. Thus, while the @sc{car} of the list @code{'(rose violet |
6569 daisy buttercup)} is @code{rose}, the rest of the list, the value | 6562 daisy buttercup)} is @code{rose}, the rest of the list, the value |
6570 returned by the @code{cdr} function, is @code{(violet daisy | 6563 returned by the @code{cdr} function, is @code{(violet daisy |
6571 buttercup)}. | 6564 buttercup)}. |
6572 | 6565 |
6573 @need 1250 | 6566 @need 800 |
6574 You can see this by evaluating the following in the usual way: | 6567 You can see this by evaluating the following in the usual way: |
6575 | 6568 |
6576 @smallexample | 6569 @smallexample |
6577 (cdr '(rose violet daisy buttercup)) | 6570 (cdr '(rose violet daisy buttercup)) |
6578 @end smallexample | 6571 @end smallexample |
7078 | 7071 |
7079 The @code{setcdr} function is similar to the @code{setcar} function, | 7072 The @code{setcdr} function is similar to the @code{setcar} function, |
7080 except that the function replaces the second and subsequent elements of | 7073 except that the function replaces the second and subsequent elements of |
7081 a list rather than the first element. | 7074 a list rather than the first element. |
7082 | 7075 |
7076 (To see how to change the last element of a list, look ahead to | |
7077 @ref{kill-new function, , The @code{kill-new} function}, which uses | |
7078 the @code{nthcdr} and @code{setcdr} functions.) | |
7079 | |
7083 @need 1200 | 7080 @need 1200 |
7084 To see how this works, set the value of the variable to a list of | 7081 To see how this works, set the value of the variable to a list of |
7085 domesticated animals by evaluating the following expression: | 7082 domesticated animals by evaluating the following expression: |
7086 | 7083 |
7087 @smallexample | 7084 @smallexample |
7320 (interactive "*p\ncZap to char: ") | 7317 (interactive "*p\ncZap to char: ") |
7321 @end smallexample | 7318 @end smallexample |
7322 | 7319 |
7323 The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies | 7320 The part within quotation marks, @code{"*p\ncZap to char:@: "}, specifies |
7324 three different things. First, and most simply, the asterisk, @samp{*}, | 7321 three different things. First, and most simply, the asterisk, @samp{*}, |
7325 causes an error to be signalled if the buffer is read-only. This means that | 7322 causes an error to be signaled if the buffer is read-only. This means that |
7326 if you try @code{zap-to-char} in a read-only buffer you will not be able to | 7323 if you try @code{zap-to-char} in a read-only buffer you will not be able to |
7327 remove text, and you will receive a message that says ``Buffer is | 7324 remove text, and you will receive a message that says ``Buffer is |
7328 read-only''; your terminal may beep at you as well. | 7325 read-only''; your terminal may beep at you as well. |
7329 | 7326 |
7330 The version 21 implementation does not have the asterisk, @samp{*}. The | 7327 The version 21 implementation does not have the asterisk, @samp{*}. The |
7336 However, the version 19 implementation copies text from a read-only | 7333 However, the version 19 implementation copies text from a read-only |
7337 buffer only because of a mistake in the implementation of | 7334 buffer only because of a mistake in the implementation of |
7338 @code{interactive}. According to the documentation for | 7335 @code{interactive}. According to the documentation for |
7339 @code{interactive}, the asterisk, @samp{*}, should prevent the | 7336 @code{interactive}, the asterisk, @samp{*}, should prevent the |
7340 @code{zap-to-char} function from doing anything at all when the buffer | 7337 @code{zap-to-char} function from doing anything at all when the buffer |
7341 is read only. The function should not copy the text to the kill ring. | 7338 is read only. In version 19, the function should not copy the text to |
7342 It is a bug that it does. | 7339 the kill ring. It is a bug that it does. |
7343 | 7340 |
7344 In version 21, @code{interactive} is implemented correctly. So the | 7341 In version 21, the function is designed to copy the text to the kill |
7342 ring; moreover, @code{interactive} is implemented correctly. So the | |
7345 asterisk, @samp{*}, had to be removed from the interactive | 7343 asterisk, @samp{*}, had to be removed from the interactive |
7346 specification. If you insert an @samp{*} and evaluate the function | 7344 specification. However, if you insert an @samp{*} yourself and |
7347 definition, then the next time you run the @code{zap-to-char} function | 7345 evaluate the function definition, then the next time you run the |
7348 on a read-only buffer, you will not copy any text. | 7346 @code{zap-to-char} function on a read-only buffer, you will not copy |
7347 any text. | |
7349 | 7348 |
7350 That change aside, and a change to the documentation, the two versions | 7349 That change aside, and a change to the documentation, the two versions |
7351 of the @code{zap-to-char} function are identical. | 7350 of the @code{zap-to-char} function are identical. |
7352 | 7351 |
7353 Let us continue with the interactive specification. | 7352 Let us continue with the interactive specification. |
7557 @unnumberedsubsec The Complete @code{kill-region} Definition | 7556 @unnumberedsubsec The Complete @code{kill-region} Definition |
7558 @end ifnottex | 7557 @end ifnottex |
7559 | 7558 |
7560 @need 1200 | 7559 @need 1200 |
7561 We will go through the @code{condition-case} code in a moment. First, | 7560 We will go through the @code{condition-case} code in a moment. First, |
7562 let us look at the complete definition of @code{kill-region}, with | 7561 let us look at the original definition of @code{kill-region}, with |
7563 comments added: | 7562 comments added (the newer definition has an optional third argument |
7563 and is more complex): | |
7564 | 7564 |
7565 @c v 21 | 7565 @c v 21 |
7566 @smallexample | 7566 @smallexample |
7567 @group | 7567 @group |
7568 (defun kill-region (beg end) | 7568 (defun kill-region (beg end) |
8073 In the past, Emacs used the @code{defvar} special form both for | 8073 In the past, Emacs used the @code{defvar} special form both for |
8074 internal variables that you would not expect a user to change and for | 8074 internal variables that you would not expect a user to change and for |
8075 variables that you do expect a user to change. Although you can still | 8075 variables that you do expect a user to change. Although you can still |
8076 use @code{defvar} for user customizable variables, please use | 8076 use @code{defvar} for user customizable variables, please use |
8077 @code{defcustom} instead, since that special form provides a path into | 8077 @code{defcustom} instead, since that special form provides a path into |
8078 the Customization commands. (@xref{defcustom, , Setting Variables | 8078 the Customization commands. (@xref{defcustom, , Specifying Variables |
8079 with @code{defcustom}}.) | 8079 using @code{defcustom}}.) |
8080 | 8080 |
8081 When you specified a variable using the @code{defvar} special form, | 8081 When you specified a variable using the @code{defvar} special form, |
8082 you could distinguish a readily settable variable from others by | 8082 you could distinguish a readily settable variable from others by |
8083 typing an asterisk, @samp{*}, in the first column of its documentation | 8083 typing an asterisk, @samp{*}, in the first column of its documentation |
8084 string. For example: | 8084 string. For example: |
8089 "*Buffer name for `shell-command' @dots{} error output. | 8089 "*Buffer name for `shell-command' @dots{} error output. |
8090 @dots{} ") | 8090 @dots{} ") |
8091 @end group | 8091 @end group |
8092 @end smallexample | 8092 @end smallexample |
8093 | 8093 |
8094 @noindent | 8094 @findex set-variable |
8095 This means that you could (and still can) use the @code{edit-options} | 8095 @noindent |
8096 command to change the value of | 8096 You could (and still can) use the @code{set-variable} command to |
8097 @code{shell-command-default-error-buffer} temporarily. | 8097 change the value of @code{shell-command-default-error-buffer} |
8098 | 8098 temporarily. However, options set using @code{set-variable} are set |
8099 @findex edit-options | 8099 only for the duration of your editing session. The new values are not |
8100 However, options set using @code{edit-options} are set only for the | 8100 saved between sessions. Each time Emacs starts, it reads the original |
8101 duration of your editing session. The new values are not saved | |
8102 between sessions. Each time Emacs starts, it reads the original | |
8103 value, unless you change the value within your @file{.emacs} file, | 8101 value, unless you change the value within your @file{.emacs} file, |
8104 either by setting it manually or by using @code{customize}. | 8102 either by setting it manually or by using @code{customize}. |
8105 @xref{Emacs Initialization, , Your @file{.emacs} File}. | 8103 @xref{Emacs Initialization, , Your @file{.emacs} File}. |
8106 | 8104 |
8107 For me, the major use of the @code{edit-options} command is to suggest | 8105 For me, the major use of the @code{set-variable} command is to suggest |
8108 variables that I might want to set in my @file{.emacs} file. I urge | 8106 variables that I might want to set in my @file{.emacs} file. There |
8109 you to look through the list. (@xref{Edit Options, , Editing Variable | 8107 are now more than 700 such variables --- far too many to remember |
8110 Values, emacs, The GNU Emacs Manual}.) | 8108 readily. Fortunately, you can press @key{TAB} after calling the |
8109 @code{M-x set-variable} command to see the list of variables. | |
8110 (@xref{Examining, , Examining and Setting Variables, emacs, | |
8111 The GNU Emacs Manual}.) | |
8111 | 8112 |
8112 @node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text | 8113 @node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text |
8113 @comment node-name, next, previous, up | 8114 @comment node-name, next, previous, up |
8114 @section @code{copy-region-as-kill} | 8115 @section @code{copy-region-as-kill} |
8115 @findex copy-region-as-kill | 8116 @findex copy-region-as-kill |
8137 @end ifnottex | 8138 @end ifnottex |
8138 | 8139 |
8139 @need 1200 | 8140 @need 1200 |
8140 Here is the complete text of the version 21 @code{copy-region-as-kill} | 8141 Here is the complete text of the version 21 @code{copy-region-as-kill} |
8141 function: | 8142 function: |
8143 | |
8144 @c !!! for no text properties, use buffer-substring-no-properties | |
8142 | 8145 |
8143 @smallexample | 8146 @smallexample |
8144 @group | 8147 @group |
8145 (defun copy-region-as-kill (beg end) | 8148 (defun copy-region-as-kill (beg end) |
8146 "Save the region as if killed, but don't kill it. | 8149 "Save the region as if killed, but don't kill it. |
8335 @code{kill-append}. When the @code{kill-append} function is | 8338 @code{kill-append}. When the @code{kill-append} function is |
8336 evaluated, it is bound to the value returned by evaluating the actual | 8339 evaluated, it is bound to the value returned by evaluating the actual |
8337 argument. In this case, this is the expression @code{(< end beg)}. | 8340 argument. In this case, this is the expression @code{(< end beg)}. |
8338 This expression does not directly determine whether the killed text in | 8341 This expression does not directly determine whether the killed text in |
8339 this command is located before or after the kill text of the last | 8342 this command is located before or after the kill text of the last |
8340 command; what is does is determine whether the value of the variable | 8343 command; what it does is determine whether the value of the variable |
8341 @code{end} is less than the value of the variable @code{beg}. If it | 8344 @code{end} is less than the value of the variable @code{beg}. If it |
8342 is, it means that the user is most likely heading towards the | 8345 is, it means that the user is most likely heading towards the |
8343 beginning of the buffer. Also, the result of evaluating the predicate | 8346 beginning of the buffer. Also, the result of evaluating the predicate |
8344 expression, @code{(< end beg)}, will be true and the text will be | 8347 expression, @code{(< end beg)}, will be true and the text will be |
8345 prepended before the previous text. On the other hand, if the value of | 8348 prepended before the previous text. On the other hand, if the value of |
8585 @dots{} It does this @var{N} times and returns the results. | 8588 @dots{} It does this @var{N} times and returns the results. |
8586 | 8589 |
8587 @findex setcdr, @r{example} | 8590 @findex setcdr, @r{example} |
8588 Thus, if we had a four element list that was supposed to be three | 8591 Thus, if we had a four element list that was supposed to be three |
8589 elements long, we could set the @sc{cdr} of the next to last element | 8592 elements long, we could set the @sc{cdr} of the next to last element |
8590 to @code{nil}, and thereby shorten the list. | 8593 to @code{nil}, and thereby shorten the list. (If you sent the last |
8591 | 8594 element to some other value than @code{nil}, which you could do, then |
8592 You can see this by evaluating the following three expressions in turn. | 8595 you would not have shortened the list.) |
8593 First set the value of @code{trees} to @code{(maple oak pine birch)}, | 8596 |
8594 then set the @sc{cdr} of its second @sc{cdr} to @code{nil} and then | 8597 You can see shortening by evaluating the following three expressions |
8595 find the value of @code{trees}: | 8598 in turn. First set the value of @code{trees} to @code{(maple oak pine |
8599 birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} | |
8600 and then find the value of @code{trees}: | |
8596 | 8601 |
8597 @smallexample | 8602 @smallexample |
8598 @group | 8603 @group |
8599 (setq trees '(maple oak pine birch)) | 8604 (setq trees '(maple oak pine birch)) |
8600 @result{} (maple oak pine birch) | 8605 @result{} (maple oak pine birch) |
8715 bringing back text that has been cut out of the buffer---the yank | 8720 bringing back text that has been cut out of the buffer---the yank |
8716 commands. However, before discussing the yank commands, it is better | 8721 commands. However, before discussing the yank commands, it is better |
8717 to learn how lists are implemented in a computer. This will make | 8722 to learn how lists are implemented in a computer. This will make |
8718 clear such mysteries as the use of the term `pointer'. | 8723 clear such mysteries as the use of the term `pointer'. |
8719 | 8724 |
8725 @need 1250 | |
8720 @node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text | 8726 @node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text |
8721 @comment node-name, next, previous, up | 8727 @comment node-name, next, previous, up |
8722 @section Review | 8728 @section Review |
8723 | 8729 |
8724 Here is a brief summary of some recently introduced functions. | 8730 Here is a brief summary of some recently introduced functions. |
8840 Optionally, how many times to repeat the search; if negative, the | 8846 Optionally, how many times to repeat the search; if negative, the |
8841 search goes backwards. | 8847 search goes backwards. |
8842 @end enumerate | 8848 @end enumerate |
8843 | 8849 |
8844 @item kill-region | 8850 @item kill-region |
8845 @itemx delete-region | 8851 @itemx delete-and-extract-region |
8846 @itemx copy-region-as-kill | 8852 @itemx copy-region-as-kill |
8847 | 8853 |
8848 @code{kill-region} cuts the text between point and mark from the | 8854 @code{kill-region} cuts the text between point and mark from the |
8849 buffer and stores that text in the kill ring, so you can get it back | 8855 buffer and stores that text in the kill ring, so you can get it back |
8850 by yanking. | 8856 by yanking. |
9144 to say, the symbol @code{flowers} holds the address of the pair of | 9150 to say, the symbol @code{flowers} holds the address of the pair of |
9145 address-boxes, the first of which holds the address of @code{violet}, | 9151 address-boxes, the first of which holds the address of @code{violet}, |
9146 and the second of which holds the address of @code{buttercup}. | 9152 and the second of which holds the address of @code{buttercup}. |
9147 | 9153 |
9148 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted | 9154 A pair of address-boxes is called a @dfn{cons cell} or @dfn{dotted |
9149 pair}. @xref{List Type, , List Type , elisp, The GNU Emacs Lisp | 9155 pair}. @xref{Cons Cell Type, , Cons Cell and List Types, elisp, The GNU Emacs Lisp |
9150 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair | 9156 Reference Manual}, and @ref{Dotted Pair Notation, , Dotted Pair |
9151 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more | 9157 Notation, elisp, The GNU Emacs Lisp Reference Manual}, for more |
9152 information about cons cells and dotted pairs. | 9158 information about cons cells and dotted pairs. |
9153 | 9159 |
9154 @need 1200 | 9160 @need 1200 |
11520 | 11526 |
11521 @c comma in printed title causes problem in Info cross reference | 11527 @c comma in printed title causes problem in Info cross reference |
11522 @item | 11528 @item |
11523 Write a function for Texinfo mode that creates an index entry at the | 11529 Write a function for Texinfo mode that creates an index entry at the |
11524 beginning of a paragraph for every @samp{@@dfn} within the paragraph. | 11530 beginning of a paragraph for every @samp{@@dfn} within the paragraph. |
11525 (In a Texinfo file, @samp{@@dfn} marks a definition. For more | 11531 (In a Texinfo file, @samp{@@dfn} marks a definition. This book is |
11526 information, see | 11532 written in Texinfo.) |
11533 | |
11534 Many of the functions you will need are described in two of the | |
11535 previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing | |
11536 Text}, and @ref{Yanking, , Yanking Text Back}. If you use | |
11537 @code{forward-paragraph} to put the index entry at the beginning of | |
11538 the paragraph, you will have to use @w{@kbd{C-h f}} | |
11539 (@code{describe-function}) to find out how to make the command go | |
11540 backwards. | |
11541 | |
11542 For more information, see | |
11527 @ifinfo | 11543 @ifinfo |
11528 @ref{Indicating, , Indicating Definitions, texinfo}.) | 11544 @ref{Indicating, , Indicating Definitions, texinfo}. |
11529 @end ifinfo | 11545 @end ifinfo |
11530 @ifhtml | 11546 @ifhtml |
11531 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}.) | 11547 @ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to |
11548 a Texinfo manual in the current directory. Or, if you are on the | |
11549 Internet, see | |
11550 @uref{http://www.gnu.org/manual/texinfo-4.6/html_node/Indicating.html} | |
11532 @end ifhtml | 11551 @end ifhtml |
11533 @iftex | 11552 @iftex |
11534 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU | 11553 ``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU |
11535 Documentation Format}.) | 11554 Documentation Format}. |
11536 @end iftex | 11555 @end iftex |
11537 @end itemize | 11556 @end itemize |
11538 | 11557 |
11539 @node Regexp Search, Counting Words, Loops & Recursion, Top | 11558 @node Regexp Search, Counting Words, Loops & Recursion, Top |
11540 @comment node-name, next, previous, up | 11559 @comment node-name, next, previous, up |
14362 @smallexample | 14381 @smallexample |
14363 (custom-set-variables '(eval-expression-print-length nil)) | 14382 (custom-set-variables '(eval-expression-print-length nil)) |
14364 @end smallexample | 14383 @end smallexample |
14365 | 14384 |
14366 @noindent | 14385 @noindent |
14367 (@xref{defcustom, , Setting Variables with @code{defcustom}}. | 14386 (@xref{defcustom, , Specifying Variables using @code{defcustom}}.) |
14368 Then evaluate the @code{lengths-list-file} expression.) | 14387 Then evaluate the @code{lengths-list-file} expression.) |
14369 | 14388 |
14370 @need 1200 | 14389 @need 1200 |
14371 The lengths' list for @file{debug.el} takes less than a second to | 14390 The lengths' list for @file{debug.el} takes less than a second to |
14372 produce and looks like this: | 14391 produce and looks like this: |
14702 (sort | 14721 (sort |
14703 (recursive-lengths-list-many-files | 14722 (recursive-lengths-list-many-files |
14704 '("../lisp/macros.el" | 14723 '("../lisp/macros.el" |
14705 "../lisp/mailalias.el" | 14724 "../lisp/mailalias.el" |
14706 "../lisp/makesum.el")) | 14725 "../lisp/makesum.el")) |
14707 '< | 14726 '<) |
14708 @end group | 14727 @end group |
14709 @end smallexample | 14728 @end smallexample |
14710 | 14729 |
14711 @need 800 | 14730 @need 800 |
14712 @noindent | 14731 @noindent |
14910 @group | 14929 @group |
14911 ;; check whether filename is that of a directory | 14930 ;; check whether filename is that of a directory |
14912 ((eq t (car (cdr (car current-directory-list)))) | 14931 ((eq t (car (cdr (car current-directory-list)))) |
14913 ;; decide whether to skip or recurse | 14932 ;; decide whether to skip or recurse |
14914 (if | 14933 (if |
14915 (equal (or "." "..") | 14934 (equal "." |
14916 (substring (car (car current-directory-list)) -1)) | 14935 (substring (car (car current-directory-list)) -1)) |
14917 ;; then do nothing if filename is that of | 14936 ;; then do nothing since filename is that of |
14918 ;; current directory or parent | 14937 ;; current directory or parent, "." or ".." |
14919 () | 14938 () |
14920 @end group | 14939 @end group |
14921 @group | 14940 @group |
14922 ;; else descend into the directory and repeat the process | 14941 ;; else descend into the directory and repeat the process |
14923 (setq el-files-list | 14942 (setq el-files-list |
16094 The fourth and subsequent arguments to @code{defcustom} specify types | 16113 The fourth and subsequent arguments to @code{defcustom} specify types |
16095 and options; these are not featured in @code{defvar}. (These | 16114 and options; these are not featured in @code{defvar}. (These |
16096 arguments are optional.) | 16115 arguments are optional.) |
16097 | 16116 |
16098 Each of these arguments consists of a keyword followed by a value. | 16117 Each of these arguments consists of a keyword followed by a value. |
16099 Each keyword starts with the character @code{:}. | 16118 Each keyword starts with the colon character @samp{:}. |
16100 | 16119 |
16101 @need 1250 | 16120 @need 1250 |
16102 For example, the customizable user option variable | 16121 For example, the customizable user option variable |
16103 @code{text-mode-hook} looks like this: | 16122 @code{text-mode-hook} looks like this: |
16104 | 16123 |
16114 | 16133 |
16115 @noindent | 16134 @noindent |
16116 The name of the variable is @code{text-mode-hook}; it has no default | 16135 The name of the variable is @code{text-mode-hook}; it has no default |
16117 value; and its documentation string tells you what it does. | 16136 value; and its documentation string tells you what it does. |
16118 | 16137 |
16119 The @code{:type} keyword tells Emacs what kind of data | 16138 The @code{:type} keyword tells Emacs the kind of data to which |
16120 @code{text-mode-hook} should be set to and how to display the value in | 16139 @code{text-mode-hook} should be set and how to display the value in a |
16121 a Customization buffer. | 16140 Customization buffer. |
16122 | 16141 |
16123 The @code{:options} keyword specifies a suggested list of values for | 16142 The @code{:options} keyword specifies a suggested list of values for |
16124 the variable. Currently, you can use @code{:options} only for a hook. | 16143 the variable. Currently, you can use @code{:options} only for a hook. |
16125 The list is only a suggestion; it is not exclusive; a person who sets | 16144 The list is only a suggestion; it is not exclusive; a person who sets |
16126 the variable may set it to other values; the list shown following the | 16145 the variable may set it to other values; the list shown following the |
16177 In spite of the warning, you certainly may edit, cut, and paste the | 16196 In spite of the warning, you certainly may edit, cut, and paste the |
16178 expression! I do all time. The purpose of the warning is to scare | 16197 expression! I do all time. The purpose of the warning is to scare |
16179 those who do not know what they are doing, so they do not | 16198 those who do not know what they are doing, so they do not |
16180 inadvertently generate an error. | 16199 inadvertently generate an error. |
16181 | 16200 |
16182 The @code{custom-set-variables} works somewhat differently than a | 16201 The @code{custom-set-variables} function works somewhat differently |
16183 @code{setq}. While I have never learned the differences, I do modify | 16202 than a @code{setq}. While I have never learned the differences, I do |
16184 the @code{custom-set-variables} expressions in my @file{.emacs} file | 16203 modify the @code{custom-set-variables} expressions in my @file{.emacs} |
16185 by hand: I make the changes in what appears to me to be a reasonable | 16204 file by hand: I make the changes in what appears to me to be a |
16186 manner and have not had any problems. Others prefer to use the | 16205 reasonable manner and have not had any problems. Others prefer to use |
16187 Customization command and let Emacs do the work for them. | 16206 the Customization command and let Emacs do the work for them. |
16188 | 16207 |
16189 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. | 16208 Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. |
16190 This function sets the various font faces. Over time, I have set a | 16209 This function sets the various font faces. Over time, I have set a |
16191 considerable number of faces. Some of the time, I re-set them using | 16210 considerable number of faces. Some of the time, I re-set them using |
16192 @code{customize}; other times, I simply edit the | 16211 @code{customize}; other times, I simply edit the |
16246 | 16265 |
16247 The first part of the file consists of comments: reminders to myself. | 16266 The first part of the file consists of comments: reminders to myself. |
16248 By now, of course, I remember these things, but when I started, I did | 16267 By now, of course, I remember these things, but when I started, I did |
16249 not. | 16268 not. |
16250 | 16269 |
16270 @need 1200 | |
16251 @smallexample | 16271 @smallexample |
16252 @group | 16272 @group |
16253 ;;;; Bob's .emacs file | 16273 ;;;; Bob's .emacs file |
16254 ; Robert J. Chassell | 16274 ; Robert J. Chassell |
16255 ; 26 September 1985 | 16275 ; 26 September 1985 |
16696 @c findex load | 16716 @c findex load |
16697 | 16717 |
16698 Many people in the GNU Emacs community have written extensions to | 16718 Many people in the GNU Emacs community have written extensions to |
16699 Emacs. As time goes by, these extensions are often included in new | 16719 Emacs. As time goes by, these extensions are often included in new |
16700 releases. For example, the Calendar and Diary packages are now part | 16720 releases. For example, the Calendar and Diary packages are now part |
16701 of the standard GNU Emacs. | 16721 of the standard GNU Emacs, as is Calc. |
16702 | |
16703 (Calc, which I consider a vital part of Emacs, would be part of the | |
16704 standard distribution except that it was so large it was packaged | |
16705 separately and no one has changed that.) | |
16706 | 16722 |
16707 You can use a @code{load} command to evaluate a complete file and | 16723 You can use a @code{load} command to evaluate a complete file and |
16708 thereby install all the functions and variables in the file into Emacs. | 16724 thereby install all the functions and variables in the file into Emacs. |
16709 For example: | 16725 For example: |
16710 | 16726 |
17078 @group | 17094 @group |
17079 (setq x-pointer-shape (string-to-int mpointer)) | 17095 (setq x-pointer-shape (string-to-int mpointer)) |
17080 (set-mouse-color "white")) | 17096 (set-mouse-color "white")) |
17081 @end group | 17097 @end group |
17082 @end smallexample | 17098 @end smallexample |
17099 | |
17100 @item | |
17101 Convert @kbd{@key{CTL}-h} into @key{DEL} and @key{DEL} | |
17102 into @kbd{@key{CTL}-h}.@* | |
17103 (Some olders keyboards needed this, although I have not seen the | |
17104 problem recently.) | |
17105 | |
17106 @smallexample | |
17107 @group | |
17108 ;; Translate `C-h' to <DEL>. | |
17109 ; (keyboard-translate ?\C-h ?\C-?) | |
17110 | |
17111 ;; Translate <DEL> to `C-h'. | |
17112 (keyboard-translate ?\C-? ?\C-h) | |
17113 @end group | |
17114 @end smallexample | |
17115 | |
17116 @item Turn off a blinking cursor! | |
17117 | |
17118 @smallexample | |
17119 @group | |
17120 (if (fboundp 'blink-cursor-mode) | |
17121 (blink-cursor-mode -1)) | |
17122 @end group | |
17123 @end smallexample | |
17124 | |
17125 @item Ignore case when using `grep'@* | |
17126 @samp{-n}@w{ } Prefix each line of output with line number@* | |
17127 @samp{-i}@w{ } Ignore case distinctions@* | |
17128 @samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} | |
17129 | |
17130 @smallexample | |
17131 (setq grep-command "grep -n -i -e ") | |
17132 @end smallexample | |
17133 | |
17134 @item Automatically uncompress compressed files when visiting them | |
17135 | |
17136 @smallexample | |
17137 (load "uncompress") | |
17138 @end smallexample | |
17139 | |
17140 @item Find an existing buffer, even if it has a different name@* | |
17141 This avoids problems with symbolic links. | |
17142 | |
17143 @smallexample | |
17144 (setq find-file-existing-other-name t) | |
17145 @end smallexample | |
17146 | |
17147 @item Set your language environment and default input method | |
17148 | |
17149 @smallexample | |
17150 @group | |
17151 (set-language-environment "latin-1") | |
17152 ;; Remember you can enable or disable multilingual text input | |
17153 ;; with the @code{toggle-input-method'} (@kbd{C-\}) command | |
17154 (setq default-input-method "latin-1-prefix") | |
17155 @end group | |
17156 @end smallexample | |
17157 | |
17158 If you want to write with Chinese `GB' characters, set this instead: | |
17159 | |
17160 @smallexample | |
17161 @group | |
17162 (set-language-environment "Chinese-GB") | |
17163 (setq default-input-method "chinese-tonepy") | |
17164 @end group | |
17165 @end smallexample | |
17083 @end itemize | 17166 @end itemize |
17167 | |
17168 @subsubheading Fixing Unpleasant Key Bindings | |
17169 @cindex Key bindings, fixing | |
17170 @cindex Bindings, key, fixing unpleasant | |
17171 | |
17172 Some systems bind keys unpleasantly. Sometimes, for example, the | |
17173 @key{CTL} key appears in an awkward spot rather than at the far left | |
17174 of the home row. | |
17175 | |
17176 Usually, when people fix these sorts of keybindings, they do not | |
17177 change their @file{~/.emacs} file. Instead, they bind the proper keys | |
17178 on their consoles with the @code{loadkeys} or @code{install-keymap} | |
17179 commands in their boot script and then include @code{xmodmap} commands | |
17180 in their @file{.xinitrc} or @file{.Xsession} file for X Windows. | |
17181 | |
17182 @need 1250 | |
17183 @noindent | |
17184 For a boot script: | |
17185 | |
17186 @smallexample | |
17187 @group | |
17188 loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz | |
17189 | |
17190 @exdent or | |
17191 | |
17192 install-keymap emacs2 | |
17193 @end group | |
17194 @end smallexample | |
17195 | |
17196 @need 1250 | |
17197 @noindent | |
17198 For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps | |
17199 Lock} key is at the far left of the home row: | |
17200 | |
17201 @smallexample | |
17202 @group | |
17203 # Bind the key labeled `Caps Lock' to `Control' | |
17204 # (Such a broken user interface suggests that keyboard manufacturers | |
17205 # think that computers are typewriters from 1885.) | |
17206 | |
17207 xmodmap -e "clear Lock" | |
17208 xmodmap -e "add Control = Caps_Lock" | |
17209 @end group | |
17210 @end smallexample | |
17211 | |
17212 @need 1250 | |
17213 @noindent | |
17214 In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} | |
17215 key to a @key{META} key: | |
17216 | |
17217 @smallexample | |
17218 @group | |
17219 # Some ill designed keyboards have a key labeled ALT and no Meta | |
17220 xmodmap -e "keysym Alt_L = Meta_L Alt_L" | |
17221 @end group | |
17222 @end smallexample | |
17084 | 17223 |
17085 @node Mode Line, , Miscellaneous, Emacs Initialization | 17224 @node Mode Line, , Miscellaneous, Emacs Initialization |
17086 @section A Modified Mode Line | 17225 @section A Modified Mode Line |
17087 @vindex default-mode-line-format | 17226 @vindex default-mode-line-format |
17088 @cindex Mode line format | 17227 @cindex Mode line format |
17157 @code{mode-line-modified} is a variable that tells whether the buffer | 17296 @code{mode-line-modified} is a variable that tells whether the buffer |
17158 has been modified, @code{mode-name} tells the name of the mode, and so | 17297 has been modified, @code{mode-name} tells the name of the mode, and so |
17159 on. However, the format looks complicated because of two features we | 17298 on. However, the format looks complicated because of two features we |
17160 have not discussed. | 17299 have not discussed. |
17161 | 17300 |
17301 @cindex Properties, in mode line example | |
17162 The first string in the mode line is a dash or hyphen, @samp{-}. In | 17302 The first string in the mode line is a dash or hyphen, @samp{-}. In |
17163 the old days, it would have been specified simply as @code{"-"}. But | 17303 the old days, it would have been specified simply as @code{"-"}. But |
17164 nowadays, Emacs can add properties to a string, such as highlighting | 17304 nowadays, Emacs can add properties to a string, such as highlighting |
17165 or, as in this case, a help feature. If you place your mouse cursor | 17305 or, as in this case, a help feature. If you place your mouse cursor |
17166 over the hyphen, some help information appears (By default, you must | 17306 over the hyphen, some help information appears (By default, you must |
17167 wait one second before the information appears. You can change that | 17307 wait one second before the information appears. You can change that |
17168 timing by changing the value of @code{tooltip-delay}.) | 17308 timing by changing the value of @code{tooltip-delay}.) |
17169 | 17309 |
17170 @need 1000 | 17310 @need 1000 |
17171 The new string format has a special syntax: | 17311 The new string format has a special syntax: |
17184 the range. It consists of a property list, a | 17324 the range. It consists of a property list, a |
17185 property name, in this case, @samp{help-echo}, followed by a value, in this | 17325 property name, in this case, @samp{help-echo}, followed by a value, in this |
17186 case, a string. The second, third, and fourth elements of this new | 17326 case, a string. The second, third, and fourth elements of this new |
17187 string format can be repeated. | 17327 string format can be repeated. |
17188 | 17328 |
17189 @xref{Text Props and Strings, , Text Properties in String, elisp, The | 17329 @xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp |
17190 GNU Emacs Lisp Reference Manual}, and see @ref{Mode Line Format, , Mode | 17330 Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, |
17191 Line Format, elisp, The GNU Emacs Lisp Reference Manual}, for more | 17331 elisp, The GNU Emacs Lisp Reference Manual}, for more information. |
17192 information. | |
17193 | 17332 |
17194 @code{mode-line-buffer-identification} | 17333 @code{mode-line-buffer-identification} |
17195 displays the current buffer name. It is a list | 17334 displays the current buffer name. It is a list |
17196 beginning @code{(#("%12b" 0 4 @dots{}}. | 17335 beginning @code{(#("%12b" 0 4 @dots{}}. |
17197 The @code{#(} begins the list. | 17336 The @code{#(} begins the list. |
17492 call-interactively(eval-last-sexp) | 17631 call-interactively(eval-last-sexp) |
17493 ---------- Buffer: *Backtrace* ---------- | 17632 ---------- Buffer: *Backtrace* ---------- |
17494 @end group | 17633 @end group |
17495 @end smallexample | 17634 @end smallexample |
17496 | 17635 |
17636 @need 1500 | |
17497 @noindent | 17637 @noindent |
17498 Finally, after you type @kbd{d} two more times, Emacs will reach the | 17638 Finally, after you type @kbd{d} two more times, Emacs will reach the |
17499 error, and the top two lines of the @file{*Backtrace*} buffer will look | 17639 error, and the top two lines of the @file{*Backtrace*} buffer will look |
17500 like this: | 17640 like this: |
17501 | 17641 |
17570 quickly until reaching a @dfn{breakpoint} where execution stops. | 17710 quickly until reaching a @dfn{breakpoint} where execution stops. |
17571 | 17711 |
17572 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs | 17712 Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs |
17573 Lisp Reference Manual}. | 17713 Lisp Reference Manual}. |
17574 | 17714 |
17715 @need 1250 | |
17575 Here is a bugged function definition for @code{triangle-recursively}. | 17716 Here is a bugged function definition for @code{triangle-recursively}. |
17576 @xref{Recursive triangle function, , Recursion in place of a counter}, | 17717 @xref{Recursive triangle function, , Recursion in place of a counter}, |
17577 for a review of it. | 17718 for a review of it. |
17578 | 17719 |
17579 @smallexample | 17720 @smallexample |
17657 Result: 3 = C-c | 17798 Result: 3 = C-c |
17658 @end smallexample | 17799 @end smallexample |
17659 | 17800 |
17660 @noindent | 17801 @noindent |
17661 This means the value of @code{number} is 3, which is @sc{ascii} | 17802 This means the value of @code{number} is 3, which is @sc{ascii} |
17662 `control-c' (the third letter of the alphabet). | 17803 `control-c' (the third letter of the alphabet, in case you need to |
17804 know this information). | |
17663 | 17805 |
17664 You can continue moving through the code until you reach the line with | 17806 You can continue moving through the code until you reach the line with |
17665 the error. Before evaluation, that line looks like this: | 17807 the error. Before evaluation, that line looks like this: |
17666 | 17808 |
17667 @smallexample | 17809 @smallexample |
17881 @cindex Duplicated words function | 18023 @cindex Duplicated words function |
17882 @cindex Words, duplicated | 18024 @cindex Words, duplicated |
17883 | 18025 |
17884 Sometimes when you you write text, you duplicate words---as with ``you | 18026 Sometimes when you you write text, you duplicate words---as with ``you |
17885 you'' near the beginning of this sentence. I find that most | 18027 you'' near the beginning of this sentence. I find that most |
17886 frequently, I duplicate ``the'; hence, I call the function for | 18028 frequently, I duplicate ``the''; hence, I call the function for |
17887 detecting duplicated words, @code{the-the}. | 18029 detecting duplicated words, @code{the-the}. |
17888 | 18030 |
17889 @need 1250 | 18031 @need 1250 |
17890 As a first step, you could use the following regular expression to | 18032 As a first step, you could use the following regular expression to |
17891 search for duplicates: | 18033 search for duplicates: |
17987 | 18129 |
17988 @menu | 18130 @menu |
17989 * rotate-yank-pointer:: Move a pointer along a list and around. | 18131 * rotate-yank-pointer:: Move a pointer along a list and around. |
17990 * yank:: Paste a copy of a clipped element. | 18132 * yank:: Paste a copy of a clipped element. |
17991 * yank-pop:: Insert first element pointed to. | 18133 * yank-pop:: Insert first element pointed to. |
18134 * ring file:: | |
17992 @end menu | 18135 @end menu |
17993 | 18136 |
17994 @node rotate-yank-pointer, yank, Kill Ring, Kill Ring | 18137 @node rotate-yank-pointer, yank, Kill Ring, Kill Ring |
17995 @comment node-name, next, previous, up | 18138 @comment node-name, next, previous, up |
17996 @appendixsec The @code{rotate-yank-pointer} Function | 18139 @appendixsec The @code{rotate-yank-pointer} Function |
18305 @end smallexample | 18448 @end smallexample |
18306 | 18449 |
18307 @noindent | 18450 @noindent |
18308 will be 1. | 18451 will be 1. |
18309 | 18452 |
18453 @need 1200 | |
18310 Consequently, the argument to @code{nthcdr} will be found as the result of | 18454 Consequently, the argument to @code{nthcdr} will be found as the result of |
18311 the expression | 18455 the expression |
18312 | 18456 |
18313 @smallexample | 18457 @smallexample |
18314 (% 1 length) | 18458 (% 1 length) |
18381 | 18525 |
18382 @noindent | 18526 @noindent |
18383 is 1. (I just checked this by placing the cursor after the expression | 18527 is 1. (I just checked this by placing the cursor after the expression |
18384 and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.) | 18528 and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.) |
18385 | 18529 |
18530 @need 2000 | |
18386 @node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body | 18531 @node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body |
18387 @unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer} | 18532 @unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer} |
18388 | 18533 |
18389 When the @code{kill-ring-yank-pointer} points to the | 18534 When the @code{kill-ring-yank-pointer} points to the |
18390 beginning of the kill ring, and the argument passed to | 18535 beginning of the kill ring, and the argument passed to |
18679 simplification for writing the program. You don't need to jump back | 18824 simplification for writing the program. You don't need to jump back |
18680 towards the beginning of the kill ring more than one place at a time | 18825 towards the beginning of the kill ring more than one place at a time |
18681 and doing this is easier than writing a function to determine the | 18826 and doing this is easier than writing a function to determine the |
18682 magnitude of the number that follows the minus sign. | 18827 magnitude of the number that follows the minus sign. |
18683 | 18828 |
18684 @node yank-pop, , yank, Kill Ring | 18829 @node yank-pop, ring file, yank, Kill Ring |
18685 @comment node-name, next, previous, up | 18830 @comment node-name, next, previous, up |
18686 @appendixsec @code{yank-pop} | 18831 @appendixsec @code{yank-pop} |
18687 @findex yank-pop | 18832 @findex yank-pop |
18688 | 18833 |
18689 After understanding @code{yank}, the @code{yank-pop} function is easy. | 18834 After understanding @code{yank}, the @code{yank-pop} function is easy. |
18726 inserted. This leaves point after the new text. If in the previous | 18871 inserted. This leaves point after the new text. If in the previous |
18727 yank, point was left before the inserted text, point and mark are now | 18872 yank, point was left before the inserted text, point and mark are now |
18728 exchanged so point is again left in front of the newly inserted text. | 18873 exchanged so point is again left in front of the newly inserted text. |
18729 That is all there is to it! | 18874 That is all there is to it! |
18730 | 18875 |
18731 @node Full Graph, GNU Free Documentation License, Kill Ring, Top | 18876 @node ring file, , yank-pop, Kill Ring |
18877 @comment node-name, next, previous, up | |
18878 @appendixsec The @file{ring.el} File | |
18879 @cindex @file{ring.el} file | |
18880 | |
18881 Interestingly, GNU Emacs posses a file called @file{ring.el} that | |
18882 provides many of the features we just discussed. But functions such | |
18883 as @code{kill-ring-yank-pointer} do not use this library, possibly | |
18884 because they were written earlier. | |
18885 | |
18886 @node Full Graph, Free Software and Free Manuals, Kill Ring, Top | |
18732 @appendix A Graph with Labelled Axes | 18887 @appendix A Graph with Labelled Axes |
18733 | 18888 |
18734 Printed axes help you understand a graph. They convey scale. In an | 18889 Printed axes help you understand a graph. They convey scale. In an |
18735 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we | 18890 earlier chapter (@pxref{Readying a Graph, , Readying a Graph}), we |
18736 wrote the code to print the body of a graph. Here we write the code | 18891 wrote the code to print the body of a graph. Here we write the code |
18872 @end smallexample | 19027 @end smallexample |
18873 | 19028 |
18874 @noindent | 19029 @noindent |
18875 As we shall see, this expression is not quite right. | 19030 As we shall see, this expression is not quite right. |
18876 | 19031 |
19032 @need 2000 | |
18877 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph | 19033 @node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph |
18878 @comment node-name, next, previous, up | 19034 @comment node-name, next, previous, up |
18879 @appendixsec The @code{print-Y-axis} Function | 19035 @appendixsec The @code{print-Y-axis} Function |
18880 @cindex Axis, print vertical | 19036 @cindex Axis, print vertical |
18881 @cindex Y axis printing | 19037 @cindex Y axis printing |
18947 | 19103 |
18948 As usual in cases like this, a complex problem becomes simpler if it is | 19104 As usual in cases like this, a complex problem becomes simpler if it is |
18949 divided into several smaller problems. | 19105 divided into several smaller problems. |
18950 | 19106 |
18951 First, consider the case when the highest value of the graph is an | 19107 First, consider the case when the highest value of the graph is an |
18952 integral multiple of five---when it is 5, 10, 15 ,or some higher | 19108 integral multiple of five---when it is 5, 10, 15, or some higher |
18953 multiple of five. We can use this value as the Y axis height. | 19109 multiple of five. We can use this value as the Y axis height. |
18954 | 19110 |
18955 A fairly simply way to determine whether a number is a multiple of | 19111 A fairly simply way to determine whether a number is a multiple of |
18956 five is to divide it by five and see if the division results in a | 19112 five is to divide it by five and see if the division results in a |
18957 remainder. If there is no remainder, the number is a multiple of | 19113 remainder. If there is no remainder, the number is a multiple of |
19247 @code{Y-axis-label-spacing}. If it is, we construct a numbered label | 19403 @code{Y-axis-label-spacing}. If it is, we construct a numbered label |
19248 using the @code{Y-axis-element} function; if not, we construct a | 19404 using the @code{Y-axis-element} function; if not, we construct a |
19249 blank label using the @code{make-string} function. The base line | 19405 blank label using the @code{make-string} function. The base line |
19250 consists of the number one followed by a tic mark. | 19406 consists of the number one followed by a tic mark. |
19251 | 19407 |
19408 @need 2000 | |
19252 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis | 19409 @node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis |
19253 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis} | 19410 @appendixsubsec The Not Quite Final Version of @code{print-Y-axis} |
19254 | 19411 |
19255 The list constructed by the @code{Y-axis-column} function is passed to | 19412 The list constructed by the @code{Y-axis-column} function is passed to |
19256 the @code{print-Y-axis} function, which inserts the list as a column. | 19413 the @code{print-Y-axis} function, which inserts the list as a column. |
19322 Emacs will print labels vertically, the top one being | 19479 Emacs will print labels vertically, the top one being |
19323 @w{@samp{10 -@w{ }}}. (The @code{print-graph} function | 19480 @w{@samp{10 -@w{ }}}. (The @code{print-graph} function |
19324 will pass the value of @code{height-of-top-line}, which | 19481 will pass the value of @code{height-of-top-line}, which |
19325 in this case would end up as 15.) | 19482 in this case would end up as 15.) |
19326 | 19483 |
19484 @need 2000 | |
19327 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph | 19485 @node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph |
19328 @appendixsec The @code{print-X-axis} Function | 19486 @appendixsec The @code{print-X-axis} Function |
19329 @cindex Axis, print horizontal | 19487 @cindex Axis, print horizontal |
19330 @cindex X axis printing | 19488 @cindex X axis printing |
19331 @cindex Print horizontal axis | 19489 @cindex Print horizontal axis |
19664 Press @key{RET} to evaluate the expression. | 19822 Press @key{RET} to evaluate the expression. |
19665 @end enumerate | 19823 @end enumerate |
19666 | 19824 |
19667 @need 1250 | 19825 @need 1250 |
19668 Emacs will print the horizontal axis like this: | 19826 Emacs will print the horizontal axis like this: |
19827 @sp 1 | |
19669 | 19828 |
19670 @smallexample | 19829 @smallexample |
19671 @group | 19830 @group |
19672 | | | | | | 19831 | | | | | |
19673 1 5 10 15 20 | 19832 1 5 10 15 20 |
19918 | | | | | 20077 | | | | |
19919 1 5 10 15 | 20078 1 5 10 15 |
19920 @end group | 20079 @end group |
19921 @end smallexample | 20080 @end smallexample |
19922 | 20081 |
20082 @need 1200 | |
19923 On the other hand, if you pass @code{print-graph} a | 20083 On the other hand, if you pass @code{print-graph} a |
19924 @code{vertical-step} value of 2, by evaluating this expression: | 20084 @code{vertical-step} value of 2, by evaluating this expression: |
19925 | 20085 |
19926 @smallexample | 20086 @smallexample |
19927 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) | 20087 (print-graph '(3 2 5 6 7 5 3 4 6 4 3 2 1) 2) |
20001 top-of-ranges)) | 20161 top-of-ranges)) |
20002 @end group | 20162 @end group |
20003 @end smallexample | 20163 @end smallexample |
20004 | 20164 |
20005 @noindent | 20165 @noindent |
20006 On my machine, this takes about an hour. It looks though 303 Lisp | 20166 On my old machine, this took about an hour. It looked though 303 Lisp |
20007 files in my copy of Emacs version 19.23. After all that computing, | 20167 files in my copy of Emacs version 19.23. After all that computing, |
20008 the @code{list-for-graph} has this value: | 20168 the @code{list-for-graph} had this value: |
20009 | 20169 |
20010 @smallexample | 20170 @smallexample |
20011 @group | 20171 @group |
20012 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99 | 20172 (537 1027 955 785 594 483 349 292 224 199 166 120 116 99 |
20013 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) | 20173 90 80 67 48 52 45 41 33 28 26 25 20 12 28 11 13 220) |
20014 @end group | 20174 @end group |
20015 @end smallexample | 20175 @end smallexample |
20016 | 20176 |
20017 @noindent | 20177 @noindent |
20018 This means that my copy of Emacs has 537 function definitions with | 20178 This means that my copy of Emacs had 537 function definitions with |
20019 fewer than 10 words or symbols in them, 1,027 function definitions | 20179 fewer than 10 words or symbols in them, 1,027 function definitions |
20020 with 10 to 19 words or symbols in them, 955 function definitions with | 20180 with 10 to 19 words or symbols in them, 955 function definitions with |
20021 20 to 29 words or symbols in them, and so on. | 20181 20 to 29 words or symbols in them, and so on. |
20022 | 20182 |
20023 Clearly, just by looking at this list we can see that most function | 20183 Clearly, just by looking at this list we can see that most function |
20061 | 20221 |
20062 @noindent | 20222 @noindent |
20063 is a function definition that says `return the value resulting from | 20223 is a function definition that says `return the value resulting from |
20064 dividing whatever is passed to me as @code{arg} by 50'. | 20224 dividing whatever is passed to me as @code{arg} by 50'. |
20065 | 20225 |
20226 @need 1200 | |
20066 Earlier, for example, we had a function @code{multiply-by-seven}; it | 20227 Earlier, for example, we had a function @code{multiply-by-seven}; it |
20067 multiplied its argument by 7. This function is similar, except it | 20228 multiplied its argument by 7. This function is similar, except it |
20068 divides its argument by 50; and, it has no name. The anonymous | 20229 divides its argument by 50; and, it has no name. The anonymous |
20069 equivalent of @code{multiply-by-seven} is: | 20230 equivalent of @code{multiply-by-seven} is: |
20070 | 20231 |
20482 (print-X-axis numbers-list horizontal-step))) | 20643 (print-X-axis numbers-list horizontal-step))) |
20483 @end group | 20644 @end group |
20484 @end smallexample | 20645 @end smallexample |
20485 @end ifnottex | 20646 @end ifnottex |
20486 | 20647 |
20648 @c qqq | |
20487 @ignore | 20649 @ignore |
20488 Graphing Definitions Re-listed | 20650 Graphing Definitions Re-listed |
20489 | 20651 |
20490 @need 1250 | 20652 @need 1250 |
20491 Here are all the graphing definitions in their final form: | 20653 Here are all the graphing definitions in their final form: |
20981 (graph-body-print | 21143 (graph-body-print |
20982 numbers-list height-of-top-line symbol-width) | 21144 numbers-list height-of-top-line symbol-width) |
20983 (print-X-axis numbers-list horizontal-step))) | 21145 (print-X-axis numbers-list horizontal-step))) |
20984 @end group | 21146 @end group |
20985 @end smallexample | 21147 @end smallexample |
21148 @c qqq | |
20986 @end ignore | 21149 @end ignore |
20987 | 21150 |
20988 @page | 21151 @page |
20989 @node Final printed graph, , Another Bug, Print Whole Graph | 21152 @node Final printed graph, , Another Bug, Print Whole Graph |
20990 @appendixsubsec The Printed Graph | 21153 @appendixsubsec The Printed Graph |
20991 | 21154 |
20992 When made and installed, you can call the @code{print-graph} command | 21155 When made and installed, you can call the @code{print-graph} command |
20993 like this: | 21156 like this: |
21157 @sp 1 | |
20994 | 21158 |
20995 @smallexample | 21159 @smallexample |
20996 @group | 21160 @group |
20997 (print-graph fiftieth-list-for-graph 50 10) | 21161 (print-graph fiftieth-list-for-graph 50 10) |
20998 @end group | 21162 @end group |
20999 @end smallexample | 21163 @end smallexample |
21000 | 21164 @sp 1 |
21165 | |
21166 @noindent | |
21001 Here is the graph: | 21167 Here is the graph: |
21002 | |
21003 @sp 2 | 21168 @sp 2 |
21004 | 21169 |
21005 @smallexample | 21170 @smallexample |
21006 @group | 21171 @group |
21007 1000 - * | 21172 1000 - * |
21029 @end group | 21194 @end group |
21030 @end smallexample | 21195 @end smallexample |
21031 | 21196 |
21032 @sp 2 | 21197 @sp 2 |
21033 | 21198 |
21199 @noindent | |
21034 The largest group of functions contain 10 -- 19 words and symbols each. | 21200 The largest group of functions contain 10 -- 19 words and symbols each. |
21035 | 21201 |
21036 @node GNU Free Documentation License, Index, Full Graph, Top | 21202 @node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top |
21203 @appendix Free Software and Free Manuals | |
21204 | |
21205 @strong{by Richard M. Stallman} | |
21206 @sp 1 | |
21207 | |
21208 The biggest deficiency in free operating systems is not in the | |
21209 software---it is the lack of good free manuals that we can include in | |
21210 these systems. Many of our most important programs do not come with | |
21211 full manuals. Documentation is an essential part of any software | |
21212 package; when an important free software package does not come with a | |
21213 free manual, that is a major gap. We have many such gaps today. | |
21214 | |
21215 Once upon a time, many years ago, I thought I would learn Perl. I got | |
21216 a copy of a free manual, but I found it hard to read. When I asked | |
21217 Perl users about alternatives, they told me that there were better | |
21218 introductory manuals---but those were not free. | |
21219 | |
21220 Why was this? The authors of the good manuals had written them for | |
21221 O'Reilly Associates, which published them with restrictive terms---no | |
21222 copying, no modification, source files not available---which exclude | |
21223 them from the free software community. | |
21224 | |
21225 That wasn't the first time this sort of thing has happened, and (to | |
21226 our community's great loss) it was far from the last. Proprietary | |
21227 manual publishers have enticed a great many authors to restrict their | |
21228 manuals since then. Many times I have heard a GNU user eagerly tell me | |
21229 about a manual that he is writing, with which he expects to help the | |
21230 GNU project---and then had my hopes dashed, as he proceeded to explain | |
21231 that he had signed a contract with a publisher that would restrict it | |
21232 so that we cannot use it. | |
21233 | |
21234 Given that writing good English is a rare skill among programmers, we | |
21235 can ill afford to lose manuals this way. | |
21236 | |
21237 @c (texinfo)uref | |
21238 (The Free Software Foundation | |
21239 @uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, , | |
21240 sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html, | |
21241 GNU manuals}, too.) | |
21242 | |
21243 Free documentation, like free software, is a matter of freedom, not | |
21244 price. The problem with these manuals was not that O'Reilly Associates | |
21245 charged a price for printed copies---that in itself is fine. (The Free | |
21246 Software Foundation sells printed copies of free GNU manuals, too.) | |
21247 But GNU manuals are available in source code form, while these manuals | |
21248 are available only on paper. GNU manuals come with permission to copy | |
21249 and modify; the Perl manuals do not. These restrictions are the | |
21250 problems. | |
21251 | |
21252 The criterion for a free manual is pretty much the same as for free | |
21253 software: it is a matter of giving all users certain | |
21254 freedoms. Redistribution (including commercial redistribution) must be | |
21255 permitted, so that the manual can accompany every copy of the program, | |
21256 on-line or on paper. Permission for modification is crucial too. | |
21257 | |
21258 As a general rule, I don't believe that it is essential for people to | |
21259 have permission to modify all sorts of articles and books. The issues | |
21260 for writings are not necessarily the same as those for software. For | |
21261 example, I don't think you or I are obliged to give permission to | |
21262 modify articles like this one, which describe our actions and our | |
21263 views. | |
21264 | |
21265 But there is a particular reason why the freedom to modify is crucial | |
21266 for documentation for free software. When people exercise their right | |
21267 to modify the software, and add or change its features, if they are | |
21268 conscientious they will change the manual too---so they can provide | |
21269 accurate and usable documentation with the modified program. A manual | |
21270 which forbids programmers to be conscientious and finish the job, or | |
21271 more precisely requires them to write a new manual from scratch if | |
21272 they change the program, does not fill our community's needs. | |
21273 | |
21274 While a blanket prohibition on modification is unacceptable, some | |
21275 kinds of limits on the method of modification pose no problem. For | |
21276 example, requirements to preserve the original author's copyright | |
21277 notice, the distribution terms, or the list of authors, are ok. It is | |
21278 also no problem to require modified versions to include notice that | |
21279 they were modified, even to have entire sections that may not be | |
21280 deleted or changed, as long as these sections deal with nontechnical | |
21281 topics. (Some GNU manuals have them.) | |
21282 | |
21283 These kinds of restrictions are not a problem because, as a practical | |
21284 matter, they don't stop the conscientious programmer from adapting the | |
21285 manual to fit the modified program. In other words, they don't block | |
21286 the free software community from making full use of the manual. | |
21287 | |
21288 However, it must be possible to modify all the technical content of | |
21289 the manual, and then distribute the result in all the usual media, | |
21290 through all the usual channels; otherwise, the restrictions do block | |
21291 the community, the manual is not free, and so we need another manual. | |
21292 | |
21293 Unfortunately, it is often hard to find someone to write another | |
21294 manual when a proprietary manual exists. The obstacle is that many | |
21295 users think that a proprietary manual is good enough---so they don't | |
21296 see the need to write a free manual. They do not see that the free | |
21297 operating system has a gap that needs filling. | |
21298 | |
21299 Why do users think that proprietary manuals are good enough? Some have | |
21300 not considered the issue. I hope this article will do something to | |
21301 change that. | |
21302 | |
21303 Other users consider proprietary manuals acceptable for the same | |
21304 reason so many people consider proprietary software acceptable: they | |
21305 judge in purely practical terms, not using freedom as a | |
21306 criterion. These people are entitled to their opinions, but since | |
21307 those opinions spring from values which do not include freedom, they | |
21308 are no guide for those of us who do value freedom. | |
21309 | |
21310 Please spread the word about this issue. We continue to lose manuals | |
21311 to proprietary publishing. If we spread the word that proprietary | |
21312 manuals are not sufficient, perhaps the next person who wants to help | |
21313 GNU by writing documentation will realize, before it is too late, that | |
21314 he must above all make it free. | |
21315 | |
21316 We can also encourage commercial publishers to sell free, copylefted | |
21317 manuals instead of proprietary ones. One way you can help this is to | |
21318 check the distribution terms of a manual before you buy it, and prefer | |
21319 copylefted manuals to non-copylefted ones. | |
21320 | |
21321 @sp 2 | |
21322 @noindent | |
21323 Note: The Free Software Foundation maintains a page on its Web site | |
21324 that lists free books available from other publishers:@* | |
21325 @uref{http://www.gnu.org/doc/other-free-books.html} | |
21326 | |
21327 | |
21328 @node GNU Free Documentation License, Index, Free Software and Free Manuals, Top | |
21037 @appendix GNU Free Documentation License | 21329 @appendix GNU Free Documentation License |
21038 | 21330 |
21039 @cindex FDL, GNU Free Documentation License | 21331 @cindex FDL, GNU Free Documentation License |
21040 @center Version 1.1, March 2000 | 21332 @center Version 1.2, November 2002 |
21041 | 21333 |
21042 @display | 21334 @display |
21043 Copyright @copyright{} 2000 Free Software Foundation, Inc. | 21335 Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. |
21044 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA | 21336 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA |
21045 | 21337 |
21046 Everyone is permitted to copy and distribute verbatim copies | 21338 Everyone is permitted to copy and distribute verbatim copies |
21047 of this license document, but changing it is not allowed. | 21339 of this license document, but changing it is not allowed. |
21048 @end display | 21340 @end display |
21049 | 21341 |
21050 @enumerate 0 | 21342 @enumerate 0 |
21051 @item | 21343 @item |
21052 PREAMBLE | 21344 PREAMBLE |
21053 | 21345 |
21054 The purpose of this License is to make a manual, textbook, or other | 21346 The purpose of this License is to make a manual, textbook, or other |
21055 written document @dfn{free} in the sense of freedom: to assure everyone | 21347 functional and useful document @dfn{free} in the sense of freedom: to |
21056 the effective freedom to copy and redistribute it, with or without | 21348 assure everyone the effective freedom to copy and redistribute it, |
21057 modifying it, either commercially or noncommercially. Secondarily, | 21349 with or without modifying it, either commercially or noncommercially. |
21058 this License preserves for the author and publisher a way to get | 21350 Secondarily, this License preserves for the author and publisher a way |
21059 credit for their work, while not being considered responsible for | 21351 to get credit for their work, while not being considered responsible |
21060 modifications made by others. | 21352 for modifications made by others. |
21061 | 21353 |
21062 This License is a kind of ``copyleft'', which means that derivative | 21354 This License is a kind of ``copyleft'', which means that derivative |
21063 works of the document must themselves be free in the same sense. It | 21355 works of the document must themselves be free in the same sense. It |
21064 complements the GNU General Public License, which is a copyleft | 21356 complements the GNU General Public License, which is a copyleft |
21065 license designed for free software. | 21357 license designed for free software. |
21073 principally for works whose purpose is instruction or reference. | 21365 principally for works whose purpose is instruction or reference. |
21074 | 21366 |
21075 @item | 21367 @item |
21076 APPLICABILITY AND DEFINITIONS | 21368 APPLICABILITY AND DEFINITIONS |
21077 | 21369 |
21078 This License applies to any manual or other work that contains a | 21370 This License applies to any manual or other work, in any medium, that |
21079 notice placed by the copyright holder saying it can be distributed | 21371 contains a notice placed by the copyright holder saying it can be |
21080 under the terms of this License. The ``Document'', below, refers to any | 21372 distributed under the terms of this License. Such a notice grants a |
21081 such manual or work. Any member of the public is a licensee, and is | 21373 world-wide, royalty-free license, unlimited in duration, to use that |
21082 addressed as ``you''. | 21374 work under the conditions stated herein. The ``Document'', below, |
21375 refers to any such manual or work. Any member of the public is a | |
21376 licensee, and is addressed as ``you''. You accept the license if you | |
21377 copy, modify or distribute the work in a way requiring permission | |
21378 under copyright law. | |
21083 | 21379 |
21084 A ``Modified Version'' of the Document means any work containing the | 21380 A ``Modified Version'' of the Document means any work containing the |
21085 Document or a portion of it, either copied verbatim, or with | 21381 Document or a portion of it, either copied verbatim, or with |
21086 modifications and/or translated into another language. | 21382 modifications and/or translated into another language. |
21087 | 21383 |
21088 A ``Secondary Section'' is a named appendix or a front-matter section of | 21384 A ``Secondary Section'' is a named appendix or a front-matter section |
21089 the Document that deals exclusively with the relationship of the | 21385 of the Document that deals exclusively with the relationship of the |
21090 publishers or authors of the Document to the Document's overall subject | 21386 publishers or authors of the Document to the Document's overall |
21091 (or to related matters) and contains nothing that could fall directly | 21387 subject (or to related matters) and contains nothing that could fall |
21092 within that overall subject. (For example, if the Document is in part a | 21388 directly within that overall subject. (Thus, if the Document is in |
21093 textbook of mathematics, a Secondary Section may not explain any | 21389 part a textbook of mathematics, a Secondary Section may not explain |
21094 mathematics.) The relationship could be a matter of historical | 21390 any mathematics.) The relationship could be a matter of historical |
21095 connection with the subject or with related matters, or of legal, | 21391 connection with the subject or with related matters, or of legal, |
21096 commercial, philosophical, ethical or political position regarding | 21392 commercial, philosophical, ethical or political position regarding |
21097 them. | 21393 them. |
21098 | 21394 |
21099 The ``Invariant Sections'' are certain Secondary Sections whose titles | 21395 The ``Invariant Sections'' are certain Secondary Sections whose titles |
21100 are designated, as being those of Invariant Sections, in the notice | 21396 are designated, as being those of Invariant Sections, in the notice |
21101 that says that the Document is released under this License. | 21397 that says that the Document is released under this License. If a |
21398 section does not fit the above definition of Secondary then it is not | |
21399 allowed to be designated as Invariant. The Document may contain zero | |
21400 Invariant Sections. If the Document does not identify any Invariant | |
21401 Sections then there are none. | |
21102 | 21402 |
21103 The ``Cover Texts'' are certain short passages of text that are listed, | 21403 The ``Cover Texts'' are certain short passages of text that are listed, |
21104 as Front-Cover Texts or Back-Cover Texts, in the notice that says that | 21404 as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
21105 the Document is released under this License. | 21405 the Document is released under this License. A Front-Cover Text may |
21406 be at most 5 words, and a Back-Cover Text may be at most 25 words. | |
21106 | 21407 |
21107 A ``Transparent'' copy of the Document means a machine-readable copy, | 21408 A ``Transparent'' copy of the Document means a machine-readable copy, |
21108 represented in a format whose specification is available to the | 21409 represented in a format whose specification is available to the |
21109 general public, whose contents can be viewed and edited directly and | 21410 general public, that is suitable for revising the document |
21110 straightforwardly with generic text editors or (for images composed of | 21411 straightforwardly with generic text editors or (for images composed of |
21111 pixels) generic paint programs or (for drawings) some widely available | 21412 pixels) generic paint programs or (for drawings) some widely available |
21112 drawing editor, and that is suitable for input to text formatters or | 21413 drawing editor, and that is suitable for input to text formatters or |
21113 for automatic translation to a variety of formats suitable for input | 21414 for automatic translation to a variety of formats suitable for input |
21114 to text formatters. A copy made in an otherwise Transparent file | 21415 to text formatters. A copy made in an otherwise Transparent file |
21115 format whose markup has been designed to thwart or discourage | 21416 format whose markup, or absence of markup, has been arranged to thwart |
21116 subsequent modification by readers is not Transparent. A copy that is | 21417 or discourage subsequent modification by readers is not Transparent. |
21117 not ``Transparent'' is called ``Opaque''. | 21418 An image format is not Transparent if used for any substantial amount |
21419 of text. A copy that is not ``Transparent'' is called ``Opaque''. | |
21118 | 21420 |
21119 Examples of suitable formats for Transparent copies include plain | 21421 Examples of suitable formats for Transparent copies include plain |
21120 @sc{ascii} without markup, Texinfo input format, La@TeX{} input format, | 21422 @sc{ascii} without markup, Texinfo input format, La@TeX{} input |
21121 @acronym{SGML} or @acronym{XML} using a publicly available | 21423 format, @acronym{SGML} or @acronym{XML} using a publicly available |
21122 @acronym{DTD}, and standard-conforming simple @acronym{HTML} designed | 21424 @acronym{DTD}, and standard-conforming simple @acronym{HTML}, |
21123 for human modification. Opaque formats include PostScript, | 21425 PostScript or @acronym{PDF} designed for human modification. Examples |
21124 @acronym{PDF}, proprietary formats that can be read and edited only by | 21426 of transparent image formats include @acronym{PNG}, @acronym{XCF} and |
21125 proprietary word processors, @acronym{SGML} or @acronym{XML} for which | 21427 @acronym{JPG}. Opaque formats include proprietary formats that can be |
21126 the @acronym{DTD} and/or processing tools are not generally available, | 21428 read and edited only by proprietary word processors, @acronym{SGML} or |
21127 and the machine-generated @acronym{HTML} produced by some word | 21429 @acronym{XML} for which the @acronym{DTD} and/or processing tools are |
21128 processors for output purposes only. | 21430 not generally available, and the machine-generated @acronym{HTML}, |
21431 PostScript or @acronym{PDF} produced by some word processors for | |
21432 output purposes only. | |
21129 | 21433 |
21130 The ``Title Page'' means, for a printed book, the title page itself, | 21434 The ``Title Page'' means, for a printed book, the title page itself, |
21131 plus such following pages as are needed to hold, legibly, the material | 21435 plus such following pages as are needed to hold, legibly, the material |
21132 this License requires to appear in the title page. For works in | 21436 this License requires to appear in the title page. For works in |
21133 formats which do not have any title page as such, ``Title Page'' means | 21437 formats which do not have any title page as such, ``Title Page'' means |
21134 the text near the most prominent appearance of the work's title, | 21438 the text near the most prominent appearance of the work's title, |
21135 preceding the beginning of the body of the text. | 21439 preceding the beginning of the body of the text. |
21440 | |
21441 A section ``Entitled XYZ'' means a named subunit of the Document whose | |
21442 title either is precisely XYZ or contains XYZ in parentheses following | |
21443 text that translates XYZ in another language. (Here XYZ stands for a | |
21444 specific section name mentioned below, such as ``Acknowledgements'', | |
21445 ``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' | |
21446 of such a section when you modify the Document means that it remains a | |
21447 section ``Entitled XYZ'' according to this definition. | |
21448 | |
21449 The Document may include Warranty Disclaimers next to the notice which | |
21450 states that this License applies to the Document. These Warranty | |
21451 Disclaimers are considered to be included by reference in this | |
21452 License, but only as regards disclaiming warranties: any other | |
21453 implication that these Warranty Disclaimers may have is void and has | |
21454 no effect on the meaning of this License. | |
21136 | 21455 |
21137 @item | 21456 @item |
21138 VERBATIM COPYING | 21457 VERBATIM COPYING |
21139 | 21458 |
21140 You may copy and distribute the Document in any medium, either | 21459 You may copy and distribute the Document in any medium, either |
21151 you may publicly display copies. | 21470 you may publicly display copies. |
21152 | 21471 |
21153 @item | 21472 @item |
21154 COPYING IN QUANTITY | 21473 COPYING IN QUANTITY |
21155 | 21474 |
21156 If you publish printed copies of the Document numbering more than 100, | 21475 If you publish printed copies (or copies in media that commonly have |
21157 and the Document's license notice requires Cover Texts, you must enclose | 21476 printed covers) of the Document, numbering more than 100, and the |
21158 the copies in covers that carry, clearly and legibly, all these Cover | 21477 Document's license notice requires Cover Texts, you must enclose the |
21478 copies in covers that carry, clearly and legibly, all these Cover | |
21159 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on | 21479 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
21160 the back cover. Both covers must also clearly and legibly identify | 21480 the back cover. Both covers must also clearly and legibly identify |
21161 you as the publisher of these copies. The front cover must present | 21481 you as the publisher of these copies. The front cover must present |
21162 the full title with all words of the title equally prominent and | 21482 the full title with all words of the title equally prominent and |
21163 visible. You may add other material on the covers in addition. | 21483 visible. You may add other material on the covers in addition. |
21171 pages. | 21491 pages. |
21172 | 21492 |
21173 If you publish or distribute Opaque copies of the Document numbering | 21493 If you publish or distribute Opaque copies of the Document numbering |
21174 more than 100, you must either include a machine-readable Transparent | 21494 more than 100, you must either include a machine-readable Transparent |
21175 copy along with each Opaque copy, or state in or with each Opaque copy | 21495 copy along with each Opaque copy, or state in or with each Opaque copy |
21176 a publicly-accessible computer-network location containing a complete | 21496 a computer-network location from which the general network-using |
21177 Transparent copy of the Document, free of added material, which the | 21497 public has access to download using public-standard network protocols |
21178 general network-using public has access to download anonymously at no | 21498 a complete Transparent copy of the Document, free of added material. |
21179 charge using public-standard network protocols. If you use the latter | 21499 If you use the latter option, you must take reasonably prudent steps, |
21180 option, you must take reasonably prudent steps, when you begin | 21500 when you begin distribution of Opaque copies in quantity, to ensure |
21181 distribution of Opaque copies in quantity, to ensure that this | 21501 that this Transparent copy will remain thus accessible at the stated |
21182 Transparent copy will remain thus accessible at the stated location | 21502 location until at least one year after the last time you distribute an |
21183 until at least one year after the last time you distribute an Opaque | 21503 Opaque copy (directly or through your agents or retailers) of that |
21184 copy (directly or through your agents or retailers) of that edition to | 21504 edition to the public. |
21185 the public. | |
21186 | 21505 |
21187 It is requested, but not required, that you contact the authors of the | 21506 It is requested, but not required, that you contact the authors of the |
21188 Document well before redistributing any large number of copies, to give | 21507 Document well before redistributing any large number of copies, to give |
21189 them a chance to provide you with an updated version of the Document. | 21508 them a chance to provide you with an updated version of the Document. |
21190 | 21509 |
21208 | 21527 |
21209 @item | 21528 @item |
21210 List on the Title Page, as authors, one or more persons or entities | 21529 List on the Title Page, as authors, one or more persons or entities |
21211 responsible for authorship of the modifications in the Modified | 21530 responsible for authorship of the modifications in the Modified |
21212 Version, together with at least five of the principal authors of the | 21531 Version, together with at least five of the principal authors of the |
21213 Document (all of its principal authors, if it has less than five). | 21532 Document (all of its principal authors, if it has fewer than five), |
21533 unless they release you from this requirement. | |
21214 | 21534 |
21215 @item | 21535 @item |
21216 State on the Title page the name of the publisher of the | 21536 State on the Title page the name of the publisher of the |
21217 Modified Version, as the publisher. | 21537 Modified Version, as the publisher. |
21218 | 21538 |
21234 | 21554 |
21235 @item | 21555 @item |
21236 Include an unaltered copy of this License. | 21556 Include an unaltered copy of this License. |
21237 | 21557 |
21238 @item | 21558 @item |
21239 Preserve the section entitled ``History'', and its title, and add to | 21559 Preserve the section Entitled ``History'', Preserve its Title, and add |
21240 it an item stating at least the title, year, new authors, and | 21560 to it an item stating at least the title, year, new authors, and |
21241 publisher of the Modified Version as given on the Title Page. If | 21561 publisher of the Modified Version as given on the Title Page. If |
21242 there is no section entitled ``History'' in the Document, create one | 21562 there is no section Entitled ``History'' in the Document, create one |
21243 stating the title, year, authors, and publisher of the Document as | 21563 stating the title, year, authors, and publisher of the Document as |
21244 given on its Title Page, then add an item describing the Modified | 21564 given on its Title Page, then add an item describing the Modified |
21245 Version as stated in the previous sentence. | 21565 Version as stated in the previous sentence. |
21246 | 21566 |
21247 @item | 21567 @item |
21252 You may omit a network location for a work that was published at | 21572 You may omit a network location for a work that was published at |
21253 least four years before the Document itself, or if the original | 21573 least four years before the Document itself, or if the original |
21254 publisher of the version it refers to gives permission. | 21574 publisher of the version it refers to gives permission. |
21255 | 21575 |
21256 @item | 21576 @item |
21257 In any section entitled ``Acknowledgments'' or ``Dedications'', | 21577 For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve |
21258 preserve the section's title, and preserve in the section all the | 21578 the Title of the section, and preserve in the section all the |
21259 substance and tone of each of the contributor acknowledgments | 21579 substance and tone of each of the contributor acknowledgements and/or |
21260 and/or dedications given therein. | 21580 dedications given therein. |
21261 | 21581 |
21262 @item | 21582 @item |
21263 Preserve all the Invariant Sections of the Document, | 21583 Preserve all the Invariant Sections of the Document, |
21264 unaltered in their text and in their titles. Section numbers | 21584 unaltered in their text and in their titles. Section numbers |
21265 or the equivalent are not considered part of the section titles. | 21585 or the equivalent are not considered part of the section titles. |
21266 | 21586 |
21267 @item | 21587 @item |
21268 Delete any section entitled ``Endorsements''. Such a section | 21588 Delete any section Entitled ``Endorsements''. Such a section |
21269 may not be included in the Modified Version. | 21589 may not be included in the Modified Version. |
21270 | 21590 |
21271 @item | 21591 @item |
21272 Do not retitle any existing section as ``Endorsements'' | 21592 Do not retitle any existing section to be Entitled ``Endorsements'' or |
21273 or to conflict in title with any Invariant Section. | 21593 to conflict in title with any Invariant Section. |
21594 | |
21595 @item | |
21596 Preserve any Warranty Disclaimers. | |
21274 @end enumerate | 21597 @end enumerate |
21275 | 21598 |
21276 If the Modified Version includes new front-matter sections or | 21599 If the Modified Version includes new front-matter sections or |
21277 appendices that qualify as Secondary Sections and contain no material | 21600 appendices that qualify as Secondary Sections and contain no material |
21278 copied from the Document, you may at your option designate some or all | 21601 copied from the Document, you may at your option designate some or all |
21279 of these sections as invariant. To do this, add their titles to the | 21602 of these sections as invariant. To do this, add their titles to the |
21280 list of Invariant Sections in the Modified Version's license notice. | 21603 list of Invariant Sections in the Modified Version's license notice. |
21281 These titles must be distinct from any other section titles. | 21604 These titles must be distinct from any other section titles. |
21282 | 21605 |
21283 You may add a section entitled ``Endorsements'', provided it contains | 21606 You may add a section Entitled ``Endorsements'', provided it contains |
21284 nothing but endorsements of your Modified Version by various | 21607 nothing but endorsements of your Modified Version by various |
21285 parties---for example, statements of peer review or that the text has | 21608 parties---for example, statements of peer review or that the text has |
21286 been approved by an organization as the authoritative definition of a | 21609 been approved by an organization as the authoritative definition of a |
21287 standard. | 21610 standard. |
21288 | 21611 |
21306 You may combine the Document with other documents released under this | 21629 You may combine the Document with other documents released under this |
21307 License, under the terms defined in section 4 above for modified | 21630 License, under the terms defined in section 4 above for modified |
21308 versions, provided that you include in the combination all of the | 21631 versions, provided that you include in the combination all of the |
21309 Invariant Sections of all of the original documents, unmodified, and | 21632 Invariant Sections of all of the original documents, unmodified, and |
21310 list them all as Invariant Sections of your combined work in its | 21633 list them all as Invariant Sections of your combined work in its |
21311 license notice. | 21634 license notice, and that you preserve all their Warranty Disclaimers. |
21312 | 21635 |
21313 The combined work need only contain one copy of this License, and | 21636 The combined work need only contain one copy of this License, and |
21314 multiple identical Invariant Sections may be replaced with a single | 21637 multiple identical Invariant Sections may be replaced with a single |
21315 copy. If there are multiple Invariant Sections with the same name but | 21638 copy. If there are multiple Invariant Sections with the same name but |
21316 different contents, make the title of each such section unique by | 21639 different contents, make the title of each such section unique by |
21317 adding at the end of it, in parentheses, the name of the original | 21640 adding at the end of it, in parentheses, the name of the original |
21318 author or publisher of that section if known, or else a unique number. | 21641 author or publisher of that section if known, or else a unique number. |
21319 Make the same adjustment to the section titles in the list of | 21642 Make the same adjustment to the section titles in the list of |
21320 Invariant Sections in the license notice of the combined work. | 21643 Invariant Sections in the license notice of the combined work. |
21321 | 21644 |
21322 In the combination, you must combine any sections entitled ``History'' | 21645 In the combination, you must combine any sections Entitled ``History'' |
21323 in the various original documents, forming one section entitled | 21646 in the various original documents, forming one section Entitled |
21324 ``History''; likewise combine any sections entitled ``Acknowledgments'', | 21647 ``History''; likewise combine any sections Entitled ``Acknowledgements'', |
21325 and any sections entitled ``Dedications''. You must delete all sections | 21648 and any sections Entitled ``Dedications''. You must delete all |
21326 entitled ``Endorsements.'' | 21649 sections Entitled ``Endorsements.'' |
21327 | 21650 |
21328 @item | 21651 @item |
21329 COLLECTIONS OF DOCUMENTS | 21652 COLLECTIONS OF DOCUMENTS |
21330 | 21653 |
21331 You may make a collection consisting of the Document and other documents | 21654 You may make a collection consisting of the Document and other documents |
21342 @item | 21665 @item |
21343 AGGREGATION WITH INDEPENDENT WORKS | 21666 AGGREGATION WITH INDEPENDENT WORKS |
21344 | 21667 |
21345 A compilation of the Document or its derivatives with other separate | 21668 A compilation of the Document or its derivatives with other separate |
21346 and independent documents or works, in or on a volume of a storage or | 21669 and independent documents or works, in or on a volume of a storage or |
21347 distribution medium, does not as a whole count as a Modified Version | 21670 distribution medium, is called an ``aggregate'' if the copyright |
21348 of the Document, provided no compilation copyright is claimed for the | 21671 resulting from the compilation is not used to limit the legal rights |
21349 compilation. Such a compilation is called an ``aggregate'', and this | 21672 of the compilation's users beyond what the individual works permit. |
21350 License does not apply to the other self-contained works thus compiled | 21673 When the Document is included in an aggregate, this License does not |
21351 with the Document, on account of their being thus compiled, if they | 21674 apply to the other works in the aggregate which are not themselves |
21352 are not themselves derivative works of the Document. | 21675 derivative works of the Document. |
21353 | 21676 |
21354 If the Cover Text requirement of section 3 is applicable to these | 21677 If the Cover Text requirement of section 3 is applicable to these |
21355 copies of the Document, then if the Document is less than one quarter | 21678 copies of the Document, then if the Document is less than one half of |
21356 of the entire aggregate, the Document's Cover Texts may be placed on | 21679 the entire aggregate, the Document's Cover Texts may be placed on |
21357 covers that surround only the Document within the aggregate. | 21680 covers that bracket the Document within the aggregate, or the |
21358 Otherwise they must appear on covers around the whole aggregate. | 21681 electronic equivalent of covers if the Document is in electronic form. |
21682 Otherwise they must appear on printed covers that bracket the whole | |
21683 aggregate. | |
21359 | 21684 |
21360 @item | 21685 @item |
21361 TRANSLATION | 21686 TRANSLATION |
21362 | 21687 |
21363 Translation is considered a kind of modification, so you may | 21688 Translation is considered a kind of modification, so you may |
21364 distribute translations of the Document under the terms of section 4. | 21689 distribute translations of the Document under the terms of section 4. |
21365 Replacing Invariant Sections with translations requires special | 21690 Replacing Invariant Sections with translations requires special |
21366 permission from their copyright holders, but you may include | 21691 permission from their copyright holders, but you may include |
21367 translations of some or all Invariant Sections in addition to the | 21692 translations of some or all Invariant Sections in addition to the |
21368 original versions of these Invariant Sections. You may include a | 21693 original versions of these Invariant Sections. You may include a |
21369 translation of this License provided that you also include the | 21694 translation of this License, and all the license notices in the |
21370 original English version of this License. In case of a disagreement | 21695 Document, and any Warranty Disclaimers, provided that you also include |
21371 between the translation and the original English version of this | 21696 the original English version of this License and the original versions |
21372 License, the original English version will prevail. | 21697 of those notices and disclaimers. In case of a disagreement between |
21698 the translation and the original version of this License or a notice | |
21699 or disclaimer, the original version will prevail. | |
21700 | |
21701 If a section in the Document is Entitled ``Acknowledgements'', | |
21702 ``Dedications'', or ``History'', the requirement (section 4) to Preserve | |
21703 its Title (section 1) will typically require changing the actual | |
21704 title. | |
21373 | 21705 |
21374 @item | 21706 @item |
21375 TERMINATION | 21707 TERMINATION |
21376 | 21708 |
21377 You may not copy, modify, sublicense, or distribute the Document except | 21709 You may not copy, modify, sublicense, or distribute the Document except |
21398 of any later version that has been published (not as a draft) by the | 21730 of any later version that has been published (not as a draft) by the |
21399 Free Software Foundation. If the Document does not specify a version | 21731 Free Software Foundation. If the Document does not specify a version |
21400 number of this License, you may choose any version ever published (not | 21732 number of this License, you may choose any version ever published (not |
21401 as a draft) by the Free Software Foundation. | 21733 as a draft) by the Free Software Foundation. |
21402 @end enumerate | 21734 @end enumerate |
21735 | |
21736 @page | |
21737 @appendixsubsec ADDENDUM: How to use this License for your documents | |
21738 | |
21739 To use this License in a document you have written, include a copy of | |
21740 the License in the document and put the following copyright and | |
21741 license notices just after the title page: | |
21742 | |
21743 @smallexample | |
21744 @group | |
21745 Copyright (C) @var{year} @var{your name}. | |
21746 Permission is granted to copy, distribute and/or modify this document | |
21747 under the terms of the GNU Free Documentation License, Version 1.2 | |
21748 or any later version published by the Free Software Foundation; | |
21749 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. | |
21750 A copy of the license is included in the section entitled ``GNU | |
21751 Free Documentation License''. | |
21752 @end group | |
21753 @end smallexample | |
21754 | |
21755 If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, | |
21756 replace the ``with...Texts.'' line with this: | |
21757 | |
21758 @smallexample | |
21759 @group | |
21760 with the Invariant Sections being @var{list their titles}, with | |
21761 the Front-Cover Texts being @var{list}, and with the Back-Cover Texts | |
21762 being @var{list}. | |
21763 @end group | |
21764 @end smallexample | |
21765 | |
21766 If you have Invariant Sections without Cover Texts, or some other | |
21767 combination of the three, merge those two alternatives to suit the | |
21768 situation. | |
21769 | |
21770 If your document contains nontrivial examples of program code, we | |
21771 recommend releasing these examples in parallel under your choice of | |
21772 free software license, such as the GNU General Public License, | |
21773 to permit their use in free software. | |
21403 | 21774 |
21404 @node Index, About the Author, GNU Free Documentation License, Top | 21775 @node Index, About the Author, GNU Free Documentation License, Top |
21405 @comment node-name, next, previous, up | 21776 @comment node-name, next, previous, up |
21406 @unnumbered Index | 21777 @unnumbered Index |
21407 | 21778 |
21470 @evenheading @thispage @| @| @thistitle | 21841 @evenheading @thispage @| @| @thistitle |
21471 @oddheading @| @| @thispage | 21842 @oddheading @| @| @thispage |
21472 @end iftex | 21843 @end iftex |
21473 | 21844 |
21474 @bye | 21845 @bye |
21846 | |
21847 @ignore | |
21848 arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf | |
21849 @end ignore |