1 |
\input texinfo @c -*-texinfo-*- |
\input texinfo @c -*-texinfo-*- |
2 |
@comment %**start of header |
@comment %**start of header |
3 |
@setfilename ../info/eintr |
@setfilename ../info/eintr |
4 |
@c sethtmlfilename emacs-lisp-intro.html |
@c sethtmlfilename emacs-lisp-intro.html |
13 |
@c set for smallbook, which works for all sizes |
@c set for smallbook, which works for all sizes |
14 |
@c of paper, and with Postscript figures >>>> |
@c of paper, and with Postscript figures >>>> |
15 |
@smallbook |
@smallbook |
16 |
@clear largebook |
@clear largebook |
17 |
@set print-postscript-figures |
@set print-postscript-figures |
18 |
@c set largebook |
@c set largebook |
19 |
@c clear print-postscript-figures |
@c clear print-postscript-figures |
21 |
|
|
22 |
@comment %**end of header |
@comment %**end of header |
23 |
|
|
24 |
@set edition-number 2.07 |
@set edition-number 2.10 |
25 |
@set update-date 2002 Aug 23 |
@set update-date 2003 July 15 |
26 |
|
|
27 |
@ignore |
@ignore |
28 |
## Summary of shell commands to create various output formats: |
## Summary of shell commands to create various output formats: |
48 |
makeinfo --xml --no-split --paragraph-indent=0 \ |
makeinfo --xml --no-split --paragraph-indent=0 \ |
49 |
--verbose emacs-lisp-intro.texi |
--verbose emacs-lisp-intro.texi |
50 |
|
|
51 |
|
#### (You must be in the same directory as the viewed file.) |
52 |
|
|
53 |
|
## View DVI output |
54 |
|
xdvi emacs-lisp-intro.dvi & |
55 |
|
|
56 |
|
## View HTML output |
57 |
|
galeon emacs-lisp-intro.html |
58 |
|
|
59 |
|
## View Info output with standalone reader |
60 |
|
info emacs-lisp-intro.info |
61 |
|
|
62 |
@end ignore |
@end ignore |
63 |
|
|
64 |
@c ================ Included Figures ================ |
@c ================ Included Figures ================ |
155 |
|
|
156 |
@c For all sized formats: print within-book cross |
@c For all sized formats: print within-book cross |
157 |
@c reference with ``...'' rather than [...] |
@c reference with ``...'' rather than [...] |
158 |
|
|
159 |
|
@c This works with the texinfo.tex file, version 2003-05-04.08, |
160 |
|
@c in the Texinfo version 4.6 of the 2003 Jun 13 distribution. |
161 |
|
|
162 |
@tex |
@tex |
163 |
% Need following so comma appears after section numbers. |
\global\def\xrefprintnodename#1{``#1''} |
|
\global\def\Ysectionnumberandtype{% |
|
|
\ifnum\secno=0 \putwordChapter\xreftie\the\chapno, \space % |
|
|
\else \ifnum \subsecno=0 \putwordSection\xreftie\the\chapno.\the\secno, \space % |
|
|
\else \ifnum \subsubsecno=0 % |
|
|
\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno, \space % |
|
|
\else % |
|
|
\putwordSection\xreftie\the\chapno.\the\secno.\the\subsecno.\the\subsubsecno, \space% |
|
|
\fi \fi \fi } |
|
|
|
|
|
\global\def\Yappendixletterandtype{% |
|
|
\ifnum\secno=0 \putwordAppendix\xreftie'char\the\appendixno{}, \space% |
|
|
\else \ifnum \subsecno=0 \putwordSection\xreftie'char\the\appendixno.\the\secno, \space % |
|
|
\else \ifnum \subsubsecno=0 % |
|
|
\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno, \space % |
|
|
\else % |
|
|
\putwordSection\xreftie'char\the\appendixno.\the\secno.\the\subsecno.\the\subsubsecno, \space % |
|
|
\fi \fi \fi } |
|
|
|
|
|
\global\def\xrefX[#1,#2,#3,#4,#5,#6]{\begingroup |
|
|
\def\printedmanual{\ignorespaces #5}% |
|
|
\def\printednodename{\ignorespaces #3}% |
|
|
\setbox1=\hbox{\printedmanual}% |
|
|
\setbox0=\hbox{\printednodename}% |
|
|
\ifdim \wd0 = 0pt |
|
|
% No printed node name was explicitly given. |
|
|
\ifx\SETxref-automatic-section-title\relax % |
|
|
% Use the actual chapter/section title appear inside |
|
|
% the square brackets. Use the real section title if we have it. |
|
|
\ifdim \wd1>0pt% |
|
|
% It is in another manual, so we don't have it. |
|
|
\def\printednodename{\ignorespaces #1}% |
|
|
\else |
|
|
\ifhavexrefs |
|
|
% We know the real title if we have the xref values. |
|
|
\def\printednodename{\refx{#1-title}}% |
|
|
\else |
|
|
% Otherwise just copy the Info node name. |
|
|
\def\printednodename{\ignorespaces #1}% |
|
|
\fi% |
|
|
\fi |
|
|
\def\printednodename{#1-title}% |
|
|
\else |
|
|
% Use the node name inside the square brackets. |
|
|
\def\printednodename{\ignorespaces #1}% |
|
|
\fi |
|
|
\fi |
|
|
% |
|
|
% If we use \unhbox0 and \unhbox1 to print the node names, TeX does not |
|
|
% insert empty discretionaries after hyphens, which means that it will |
|
|
% not find a line break at a hyphen in a node names. Since some manuals |
|
|
% are best written with fairly long node names, containing hyphens, this |
|
|
% is a loss. Therefore, we give the text of the node name again, so it |
|
|
% is as if TeX is seeing it for the first time. |
|
|
\ifdim \wd1 > 0pt |
|
|
\putwordsection{} ``\printednodename'' in \cite{\printedmanual}% |
|
|
\else |
|
|
% _ (for example) has to be the character _ for the purposes of the |
|
|
% control sequence corresponding to the node, but it has to expand |
|
|
% into the usual \leavevmode...\vrule stuff for purposes of |
|
|
% printing. So we \turnoffactive for the \refx-snt, back on for the |
|
|
% printing, back off for the \refx-pg. |
|
|
{\turnoffactive \refx{#1-snt}{}}% |
|
|
% \space [\printednodename],\space % <= original |
|
|
% \putwordsection{} ``\printednodename'',\space |
|
|
``\printednodename'',\space |
|
|
\turnoffactive \putwordpage\tie\refx{#1-pg}{}% |
|
|
\fi |
|
|
\endgroup} |
|
164 |
@end tex |
@end tex |
165 |
|
|
166 |
@c ---------------------------------------------------- |
@c ---------------------------------------------------- |
172 |
@end direntry |
@end direntry |
173 |
|
|
174 |
@copying |
@copying |
175 |
This is an introduction to @cite{Programming in Emacs Lisp}, for |
This is an @cite{Introduction to Programming in Emacs Lisp}, for |
176 |
people who are not programmers. |
people who are not programmers. |
177 |
|
@sp 1 |
178 |
Edition @value{edition-number}, @value{update-date} |
Edition @value{edition-number}, @value{update-date} |
179 |
|
@sp 1 |
180 |
|
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, |
181 |
|
2002, 2003 Free Software Foundation, Inc. |
182 |
|
@sp 1 |
183 |
|
|
184 |
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1997, 2001, 2002 Free Software Foundation, Inc. |
@iftex |
185 |
@sp 2 |
Published by the:@* |
186 |
|
|
187 |
Published by the Free Software Foundation, Inc.@* |
GNU Press, @hfill @uref{http://www.gnupress.org}@* |
188 |
59 Temple Place, Suite 330@* |
a division of the @hfill General: @email{press@@gnu.org}@* |
189 |
Boston, MA 02111-1307 USA@* |
Free Software Foundation, Inc. @hfill Orders:@w{ } @email{sales@@gnu.org}@* |
190 |
|
59 Temple Place, Suite 330 @hfill Tel: +1 (617) 542-5942@* |
191 |
|
Boston, MA 02111-1307 USA @hfill Fax: +1 (617) 542-2652@* |
192 |
|
@end iftex |
193 |
|
|
194 |
|
@ifnottex |
195 |
|
Published by the: |
196 |
|
|
197 |
|
@example |
198 |
|
GNU Press, Website: http://www.gnupress.org |
199 |
|
a division of the General: press@@gnu.org |
200 |
|
Free Software Foundation, Inc. Orders: sales@@gnu.org |
201 |
|
59 Temple Place, Suite 330 Tel: +1 (617) 542-5942 |
202 |
|
Boston, MA 02111-1307 USA Fax: +1 (617) 542-2652 |
203 |
|
@end example |
204 |
|
@end ifnottex |
205 |
|
|
206 |
|
@sp 1 |
207 |
@c Printed copies are available for $30 each.@* |
@c Printed copies are available for $30 each.@* |
208 |
ISBN 1-882114-43-4 |
ISBN 1-882114-43-4 |
209 |
|
|
236 |
@sp 2 |
@sp 2 |
237 |
@center @titlefont{Programming in Emacs Lisp} |
@center @titlefont{Programming in Emacs Lisp} |
238 |
@sp 2 |
@sp 2 |
239 |
@center Second Edition |
@center Revised Second Edition |
240 |
@sp 4 |
@sp 4 |
241 |
@center by Robert J. Chassell |
@center by Robert J. Chassell |
242 |
|
|
252 |
@end iftex |
@end iftex |
253 |
|
|
254 |
@ifnothtml |
@ifnothtml |
255 |
|
@c Keep T.O.C. short by tightening up for largebook |
|
@c Keep T.O.C. short by tightening up. |
|
256 |
@ifset largebook |
@ifset largebook |
257 |
@tex |
@tex |
258 |
\global\parskip 2pt plus 1pt |
\global\parskip 2pt plus 1pt |
259 |
\global\advance\baselineskip by -1pt |
\global\advance\baselineskip by -1pt |
260 |
@end tex |
@end tex |
261 |
@end ifset |
@end ifset |
262 |
|
@end ifnothtml |
263 |
|
|
264 |
@shortcontents |
@shortcontents |
265 |
@contents |
@contents |
266 |
|
|
|
@ifset largebook |
|
|
@tex |
|
|
\global\parskip 6pt plus 1pt |
|
|
\global\advance\baselineskip by 1pt |
|
|
@end tex |
|
|
@end ifset |
|
|
|
|
|
@end ifnothtml |
|
|
|
|
|
@c >>>> Set pageno appropriately <<<< |
|
|
|
|
|
@c The first page of the Preface is a roman numeral; it is the first |
|
|
@c right handed page after the Table of Contents; hence the following |
|
|
@c setting must be for an odd negative number. |
|
|
|
|
|
@c if largebook, there are 8 pages in Table of Contents |
|
|
@ifset largebook |
|
|
@iftex |
|
|
@pageno = -9 |
|
|
@end iftex |
|
|
@end ifset |
|
|
|
|
|
@c if smallbook, there are 10 pages in Table of Contents |
|
|
@ifclear largebook |
|
|
@iftex |
|
|
@pageno = -11 |
|
|
@end iftex |
|
|
@end ifclear |
|
|
|
|
267 |
@ifnottex |
@ifnottex |
268 |
@node Top, Preface, (dir), (dir) |
@node Top, Preface, (dir), (dir) |
269 |
@top An Introduction to Programming in Emacs Lisp |
@top An Introduction to Programming in Emacs Lisp |
298 |
* the-the:: An appendix: how to find reduplicated words. |
* the-the:: An appendix: how to find reduplicated words. |
299 |
* Kill Ring:: An appendix: how the kill ring works. |
* Kill Ring:: An appendix: how the kill ring works. |
300 |
* Full Graph:: How to create a graph with labelled axes. |
* Full Graph:: How to create a graph with labelled axes. |
301 |
|
* Free Software and Free Manuals:: |
302 |
* GNU Free Documentation License:: |
* GNU Free Documentation License:: |
303 |
* Index:: |
* Index:: |
304 |
* About the Author:: |
* About the Author:: |
718 |
* rotate-yank-pointer:: Move a pointer along a list and around. |
* rotate-yank-pointer:: Move a pointer along a list and around. |
719 |
* yank:: Paste a copy of a clipped element. |
* yank:: Paste a copy of a clipped element. |
720 |
* yank-pop:: Insert first element pointed to. |
* yank-pop:: Insert first element pointed to. |
721 |
|
* ring file:: |
722 |
|
|
723 |
The @code{rotate-yank-pointer} Function |
The @code{rotate-yank-pointer} Function |
724 |
|
|
772 |
@end detailmenu |
@end detailmenu |
773 |
@end menu |
@end menu |
774 |
|
|
775 |
|
@c >>>> Set pageno appropriately <<<< |
776 |
|
|
777 |
|
@c The first page of the Preface is a roman numeral; it is the first |
778 |
|
@c right handed page after the Table of Contents; hence the following |
779 |
|
@c setting must be for an odd negative number. |
780 |
|
|
781 |
|
@iftex |
782 |
|
@global@pageno = -11 |
783 |
|
@end iftex |
784 |
|
|
785 |
@node Preface, List Processing, Top, Top |
@node Preface, List Processing, Top, Top |
786 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
787 |
@unnumbered Preface |
@unnumbered Preface |
1040 |
@headings off |
@headings off |
1041 |
@evenheading @thispage @| @| @thischapter |
@evenheading @thispage @| @| @thischapter |
1042 |
@oddheading @thissection @| @| @thispage |
@oddheading @thissection @| @| @thispage |
1043 |
@pageno = 1 |
@global@pageno = 1 |
1044 |
@end iftex |
@end iftex |
1045 |
|
|
1046 |
@node List Processing, Practicing Evaluation, Preface, Top |
@node List Processing, Practicing Evaluation, Preface, Top |
1492 |
of locating the definition or set of instructions. What we see is the |
of locating the definition or set of instructions. What we see is the |
1493 |
name through which the instructions can be found. Names of people |
name through which the instructions can be found. Names of people |
1494 |
work the same way. I can be referred to as @samp{Bob}; however, I am |
work the same way. I can be referred to as @samp{Bob}; however, I am |
1495 |
not the letters @samp{B}, @samp{o}, @samp{b} but am the consciousness |
not the letters @samp{B}, @samp{o}, @samp{b} but am, or were, the |
1496 |
consistently associated with a particular life-form. The name is not |
consciousness consistently associated with a particular life-form. |
1497 |
me, but it can be used to refer to me. |
The name is not me, but it can be used to refer to me. |
1498 |
|
|
1499 |
In Lisp, one set of instructions can be attached to several names. |
In Lisp, one set of instructions can be attached to several names. |
1500 |
For example, the computer instructions for adding numbers can be |
For example, the computer instructions for adding numbers can be |
1958 |
@code{+} must have values that are numbers, since @code{+} adds numbers. |
@code{+} must have values that are numbers, since @code{+} adds numbers. |
1959 |
Other functions use different kinds of data for their arguments. |
Other functions use different kinds of data for their arguments. |
1960 |
|
|
1961 |
|
@need 1250 |
1962 |
@findex concat |
@findex concat |
1963 |
For example, the @code{concat} function links together or unites two or |
For example, the @code{concat} function links together or unites two or |
1964 |
more strings of text to produce a string. The arguments are strings. |
more strings of text to produce a string. The arguments are strings. |
2275 |
@smallexample |
@smallexample |
2276 |
@group |
@group |
2277 |
(message "He saw %d %s" |
(message "He saw %d %s" |
2278 |
(- fill-column 34) |
(- fill-column 32) |
2279 |
(concat "red " |
(concat "red " |
2280 |
(substring |
(substring |
2281 |
"The quick brown foxes jumped." 16 21) |
"The quick brown foxes jumped." 16 21) |
2487 |
steepest. You have now climbed the most difficult part; what remains |
steepest. You have now climbed the most difficult part; what remains |
2488 |
becomes easier as you progress onwards. |
becomes easier as you progress onwards. |
2489 |
|
|
2490 |
|
@need 1000 |
2491 |
In summary, |
In summary, |
2492 |
|
|
2493 |
@itemize @bullet |
@itemize @bullet |
3487 |
each argument in the same order it is specified in the |
each argument in the same order it is specified in the |
3488 |
@code{interactive} list. In the string, each part is separated from |
@code{interactive} list. In the string, each part is separated from |
3489 |
the next part by a @samp{\n}, which is a newline. For example, you |
the next part by a @samp{\n}, which is a newline. For example, you |
3490 |
could follow @code{"BAppend to buffer:@: "} with a @samp{\n}) and an |
could follow @code{"BAppend to buffer:@: "} with a @samp{\n} and an |
3491 |
@samp{r}. This would cause Emacs to pass the values of point and mark |
@samp{r}. This would cause Emacs to pass the values of point and mark |
3492 |
to the function as well as prompt you for the buffer---three arguments |
to the function as well as prompt you for the buffer---three arguments |
3493 |
in all. |
in all. |
4344 |
prompt for information. Parts of the string are separated by |
prompt for information. Parts of the string are separated by |
4345 |
newlines, @samp{\n}. |
newlines, @samp{\n}. |
4346 |
|
|
4347 |
|
@need 1000 |
4348 |
Common code characters are: |
Common code characters are: |
4349 |
|
|
4350 |
@table @code |
@table @code |
4475 |
can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of |
can contain @samp{%s}, @samp{%d}, or @samp{%c} to print the value of |
4476 |
arguments that follow the string. The argument used by @samp{%s} must |
arguments that follow the string. The argument used by @samp{%s} must |
4477 |
be a string or a symbol; the argument used by @samp{%d} must be a |
be a string or a symbol; the argument used by @samp{%d} must be a |
4478 |
number. The argument used by @samp{%c} must be an ascii code number; |
number. The argument used by @samp{%c} must be an @sc{ascii} code |
4479 |
it will be printed as the character with that @sc{ascii} code. |
number; it will be printed as the character with that @sc{ascii} code. |
4480 |
|
|
4481 |
@item setq |
@item setq |
4482 |
@itemx set |
@itemx set |
4584 |
In versions 20 and higher, when a function is written in Emacs Lisp, |
In versions 20 and higher, when a function is written in Emacs Lisp, |
4585 |
@code{describe-function} will also tell you the location of the |
@code{describe-function} will also tell you the location of the |
4586 |
function definition. If you move point over the file name and press |
function definition. If you move point over the file name and press |
4587 |
the @key{RET} key, which is this case means @code{help-follow} rather |
the @key{RET} key, which in this case means @code{help-follow} rather |
4588 |
than `return' or `enter', Emacs will take you directly to the function |
than `return' or `enter', Emacs will take you directly to the function |
4589 |
definition. |
definition. |
4590 |
|
|
4599 |
the locations of the functions, variables, and other items to which |
the locations of the functions, variables, and other items to which |
4600 |
@code{find-tags} jumps. |
@code{find-tags} jumps. |
4601 |
|
|
4602 |
To use the @code{find-tags} command, type @kbd{M-.} (i.e., type the |
To use the @code{find-tags} command, type @kbd{M-.} (i.e., press the |
4603 |
@key{META} key and the period key at the same time, or else type the |
period key while holding down the @key{META} key, or else type the |
4604 |
@key{ESC} key and then type the period key), and then, at the prompt, |
@key{ESC} key and then type the period key), and then, at the prompt, |
4605 |
type in the name of the function whose source code you want to see, |
type in the name of the function whose source code you want to see, |
4606 |
such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will |
such as @code{mark-whole-buffer}, and then type @key{RET}. Emacs will |
4620 |
the @file{/usr/local/share/emacs/} directory; thus you would use the |
the @file{/usr/local/share/emacs/} directory; thus you would use the |
4621 |
@code{M-x visit-tags-table} command and specify a pathname such as |
@code{M-x visit-tags-table} command and specify a pathname such as |
4622 |
@file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or |
@file{/usr/local/share/emacs/21.0.100/lisp/TAGS} or |
4623 |
@file{/usr/local/src/emacs/lisp/TAGS}. If the tags table has |
@file{/usr/local/src/emacs/src/TAGS}. If the tags table has |
4624 |
not already been created, you will have to create it yourself. |
not already been created, you will have to create it yourself. |
4625 |
|
|
4626 |
@need 1250 |
@need 1250 |
4845 |
to the @code{simplified-beginning-of-buffer} function described in the |
to the @code{simplified-beginning-of-buffer} function described in the |
4846 |
previous section. |
previous section. |
4847 |
|
|
4848 |
|
@need 1250 |
4849 |
@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer |
@node Body of mark-whole-buffer, , mark-whole-buffer overview, mark-whole-buffer |
4850 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
4851 |
@subsection Body of @code{mark-whole-buffer} |
@subsection Body of @code{mark-whole-buffer} |
5430 |
reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they |
reverse of @code{append-to-buffer} or @code{copy-to-buffer}, since they |
5431 |
copy a region of text @emph{from} the current buffer to another buffer. |
copy a region of text @emph{from} the current buffer to another buffer. |
5432 |
|
|
5433 |
|
Here is a discussion based on the original code. The code was |
5434 |
|
simplified in 2003 and is harder to understand. |
5435 |
|
|
5436 |
In addition, this code illustrates the use of @code{interactive} with a |
In addition, this code illustrates the use of @code{interactive} with a |
5437 |
buffer that might be @dfn{read-only} and the important distinction |
buffer that might be @dfn{read-only} and the important distinction |
5438 |
between the name of an object and the object actually referred to. |
between the name of an object and the object actually referred to. |
5638 |
what is ``not true'' is false and what is ``not false'' is true. |
what is ``not true'' is false and what is ``not false'' is true. |
5639 |
|
|
5640 |
Using this test, the @code{if} expression works as follows: when the |
Using this test, the @code{if} expression works as follows: when the |
5641 |
value of the variable @code{buffer} is actually a buffer rather then |
value of the variable @code{buffer} is actually a buffer rather than |
5642 |
its name, the true-or-false-test returns false and the @code{if} |
its name, the true-or-false-test returns false and the @code{if} |
5643 |
expression does not evaluate the then-part. This is fine, since we do |
expression does not evaluate the then-part. This is fine, since we do |
5644 |
not need to do anything to the variable @code{buffer} if it really is |
not need to do anything to the variable @code{buffer} if it really is |
5786 |
mark is still accessible; it is recorded on the mark ring and you can |
mark is still accessible; it is recorded on the mark ring and you can |
5787 |
go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is |
go back to it with @kbd{C-u C-@key{SPC}}.) Meanwhile, point is |
5788 |
located at the beginning of the inserted text, which is where it was |
located at the beginning of the inserted text, which is where it was |
5789 |
before you called the insert function. |
before you called the insert function, the position of which was saved |
5790 |
|
by the first @code{save-excursion}. |
5791 |
|
|
5792 |
@need 1250 |
@need 1250 |
5793 |
The whole @code{let} expression looks like this: |
The whole @code{let} expression looks like this: |
6101 |
The number that results from all this is passed to @code{goto-char} and |
The number that results from all this is passed to @code{goto-char} and |
6102 |
the cursor is moved to that point. |
the cursor is moved to that point. |
6103 |
|
|
6104 |
|
@need 1500 |
6105 |
@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer |
@node beginning-of-buffer complete, , beginning-of-buffer opt arg, beginning-of-buffer |
6106 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
6107 |
@subsection The Complete @code{beginning-of-buffer} |
@subsection The Complete @code{beginning-of-buffer} |
6108 |
|
|
6109 |
@need 800 |
@need 1000 |
6110 |
Here is the complete text of the @code{beginning-of-buffer} function: |
Here is the complete text of the @code{beginning-of-buffer} function: |
6111 |
|
@sp 1 |
6112 |
|
|
6113 |
@smallexample |
@smallexample |
6114 |
@group |
@group |
6117 |
leave mark at previous position. |
leave mark at previous position. |
6118 |
With arg N, put point N/10 of the way |
With arg N, put point N/10 of the way |
6119 |
from the true beginning. |
from the true beginning. |
6120 |
|
@end group |
6121 |
|
@group |
6122 |
Don't use this in Lisp programs! |
Don't use this in Lisp programs! |
6123 |
\(goto-char (point-min)) is faster |
\(goto-char (point-min)) is faster |
6124 |
and does not set the mark." |
and does not set the mark." |
6226 |
@section @code{optional} Argument Exercise |
@section @code{optional} Argument Exercise |
6227 |
|
|
6228 |
Write an interactive function with an optional argument that tests |
Write an interactive function with an optional argument that tests |
6229 |
whether its argument, a number, is greater or less than the value of |
whether its argument, a number, is greater than or equal to, or else, |
6230 |
@code{fill-column}, and tells you which, in a message. However, if you |
less than the value of @code{fill-column}, and tells you which, in a |
6231 |
do not pass an argument to the function, use 56 as a default value. |
message. However, if you do not pass an argument to the function, use |
6232 |
|
56 as a default value. |
6233 |
|
|
6234 |
@node Narrowing & Widening, car cdr & cons, More Complex, Top |
@node Narrowing & Widening, car cdr & cons, More Complex, Top |
6235 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
6358 |
The @code{what-line} command tells you the number of the line in which |
The @code{what-line} command tells you the number of the line in which |
6359 |
the cursor is located. The function illustrates the use of the |
the cursor is located. The function illustrates the use of the |
6360 |
@code{save-restriction} and @code{save-excursion} commands. Here is the |
@code{save-restriction} and @code{save-excursion} commands. Here is the |
6361 |
text of the function in full: |
original text of the function: |
6362 |
|
|
6363 |
@smallexample |
@smallexample |
6364 |
@group |
@group |
6374 |
@end group |
@end group |
6375 |
@end smallexample |
@end smallexample |
6376 |
|
|
6377 |
The function has a documentation line and is interactive, as you would |
(In recent versions of GNU Emacs, the @code{what-line} function has |
6378 |
expect. The next two lines use the functions @code{save-restriction} and |
been expanded to tell you your line number in a narrowed buffer as |
6379 |
@code{widen}. |
well as your line number in a widened buffer. The recent version is |
6380 |
|
more complex than the version shown here. If you feel adventurous, |
6381 |
|
you might want to look at it after figuring out how this version |
6382 |
|
works. The newer version uses a conditional to determine whether the |
6383 |
|
buffer has been narrowed, and rather than use @code{beginning-of-line} |
6384 |
|
to move point to the beginning of the current line, if need be, the |
6385 |
|
function uses @code{(forward-line 0)}.) |
6386 |
|
|
6387 |
|
The function as shown here has a documentation line and is |
6388 |
|
interactive, as you would expect. The next two lines use the |
6389 |
|
functions @code{save-restriction} and @code{widen}. |
6390 |
|
|
6391 |
The @code{save-restriction} special form notes whatever narrowing is in |
The @code{save-restriction} special form notes whatever narrowing is in |
6392 |
effect, if any, in the current buffer and restores that narrowing after |
effect, if any, in the current buffer and restores that narrowing after |
6432 |
something such as @samp{Line 243}. |
something such as @samp{Line 243}. |
6433 |
|
|
6434 |
@need 1200 |
@need 1200 |
6435 |
|
|
6436 |
The number that is printed in place of the @samp{%d} is computed by the |
The number that is printed in place of the @samp{%d} is computed by the |
6437 |
last line of the function: |
last line of the function: |
6438 |
|
|
6458 |
|
|
6459 |
Write a function that will display the first 60 characters of the |
Write a function that will display the first 60 characters of the |
6460 |
current buffer, even if you have narrowed the buffer to its latter |
current buffer, even if you have narrowed the buffer to its latter |
6461 |
half so that the first line is inaccessible. Restore point, mark, |
half so that the first line is inaccessible. Restore point, mark, and |
6462 |
and narrowing. For this exercise, you need to use |
narrowing. For this exercise, you need to use a whole potpourri of |
6463 |
@code{save-restriction}, @code{widen}, @code{goto-char}, |
functions, including @code{save-restriction}, @code{widen}, |
6464 |
@code{point-min}, @code{buffer-substring}, @code{message}, and other |
@code{goto-char}, @code{point-min}, @code{message}, and |
6465 |
functions, a whole potpourri. |
@code{buffer-substring}. |
6466 |
|
|
6467 |
|
@cindex Properties, mention of @code{buffer-substring-no-properties} |
6468 |
|
(@code{buffer-substring} is a previously unmentioned function you will |
6469 |
|
have to investigate yourself; or perhaps you will have to use |
6470 |
|
@code{buffer-substring-no-properties} @dots{}, yet another function |
6471 |
|
and one that introduces text properties, a feature otherwise not |
6472 |
|
discussed here. @xref{Text Properties, , Text Properties, elisp, The |
6473 |
|
GNU Emacs Lisp Reference Manual}. Additionally, do you really need |
6474 |
|
@code{goto-char} or @code{point-min}? Or can you write the function |
6475 |
|
without them?) |
6476 |
|
|
6477 |
@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top |
@node car cdr & cons, Cutting & Storing Text, Narrowing & Widening, Top |
6478 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
6554 |
returned by the @code{cdr} function, is @code{(violet daisy |
returned by the @code{cdr} function, is @code{(violet daisy |
6555 |
buttercup)}. |
buttercup)}. |
6556 |
|
|
6557 |
@need 1250 |
@need 800 |
6558 |
You can see this by evaluating the following in the usual way: |
You can see this by evaluating the following in the usual way: |
6559 |
|
|
6560 |
@smallexample |
@smallexample |
7064 |
except that the function replaces the second and subsequent elements of |
except that the function replaces the second and subsequent elements of |
7065 |
a list rather than the first element. |
a list rather than the first element. |
7066 |
|
|
7067 |
|
(To see how to change the last element of a list, look ahead to |
7068 |
|
@ref{kill-new function, , The @code{kill-new} function}, which uses |
7069 |
|
the @code{nthcdr} and @code{setcdr} functions.) |
7070 |
|
|
7071 |
@need 1200 |
@need 1200 |
7072 |
To see how this works, set the value of the variable to a list of |
To see how this works, set the value of the variable to a list of |
7073 |
domesticated animals by evaluating the following expression: |
domesticated animals by evaluating the following expression: |
7326 |
@code{interactive}. According to the documentation for |
@code{interactive}. According to the documentation for |
7327 |
@code{interactive}, the asterisk, @samp{*}, should prevent the |
@code{interactive}, the asterisk, @samp{*}, should prevent the |
7328 |
@code{zap-to-char} function from doing anything at all when the buffer |
@code{zap-to-char} function from doing anything at all when the buffer |
7329 |
is read only. The function should not copy the text to the kill ring. |
is read only. In version 19, the function should not copy the text to |
7330 |
It is a bug that it does. |
the kill ring. It is a bug that it does. |
7331 |
|
|
7332 |
In version 21, @code{interactive} is implemented correctly. So the |
In version 21, the function is designed to copy the text to the kill |
7333 |
|
ring; moreover, @code{interactive} is implemented correctly. So the |
7334 |
asterisk, @samp{*}, had to be removed from the interactive |
asterisk, @samp{*}, had to be removed from the interactive |
7335 |
specification. If you insert an @samp{*} and evaluate the function |
specification. However, if you insert an @samp{*} yourself and |
7336 |
definition, then the next time you run the @code{zap-to-char} function |
evaluate the function definition, then the next time you run the |
7337 |
on a read-only buffer, you will not copy any text. |
@code{zap-to-char} function on a read-only buffer, you will not copy |
7338 |
|
any text. |
7339 |
|
|
7340 |
That change aside, and a change to the documentation, the two versions |
That change aside, and a change to the documentation, the two versions |
7341 |
of the @code{zap-to-char} function are identical. |
of the @code{zap-to-char} function are identical. |
7549 |
|
|
7550 |
@need 1200 |
@need 1200 |
7551 |
We will go through the @code{condition-case} code in a moment. First, |
We will go through the @code{condition-case} code in a moment. First, |
7552 |
let us look at the complete definition of @code{kill-region}, with |
let us look at the original definition of @code{kill-region}, with |
7553 |
comments added: |
comments added (the newer definition has an optional third argument |
7554 |
|
and is more complex): |
7555 |
|
|
7556 |
@c v 21 |
@c v 21 |
7557 |
@smallexample |
@smallexample |
8131 |
Here is the complete text of the version 21 @code{copy-region-as-kill} |
Here is the complete text of the version 21 @code{copy-region-as-kill} |
8132 |
function: |
function: |
8133 |
|
|
8134 |
|
@c !!! for no text properties, use buffer-substring-no-properties |
8135 |
|
|
8136 |
@smallexample |
@smallexample |
8137 |
@group |
@group |
8138 |
(defun copy-region-as-kill (beg end) |
(defun copy-region-as-kill (beg end) |
8330 |
argument. In this case, this is the expression @code{(< end beg)}. |
argument. In this case, this is the expression @code{(< end beg)}. |
8331 |
This expression does not directly determine whether the killed text in |
This expression does not directly determine whether the killed text in |
8332 |
this command is located before or after the kill text of the last |
this command is located before or after the kill text of the last |
8333 |
command; what is does is determine whether the value of the variable |
command; what it does is determine whether the value of the variable |
8334 |
@code{end} is less than the value of the variable @code{beg}. If it |
@code{end} is less than the value of the variable @code{beg}. If it |
8335 |
is, it means that the user is most likely heading towards the |
is, it means that the user is most likely heading towards the |
8336 |
beginning of the buffer. Also, the result of evaluating the predicate |
beginning of the buffer. Also, the result of evaluating the predicate |
8580 |
@findex setcdr, @r{example} |
@findex setcdr, @r{example} |
8581 |
Thus, if we had a four element list that was supposed to be three |
Thus, if we had a four element list that was supposed to be three |
8582 |
elements long, we could set the @sc{cdr} of the next to last element |
elements long, we could set the @sc{cdr} of the next to last element |
8583 |
to @code{nil}, and thereby shorten the list. |
to @code{nil}, and thereby shorten the list. (If you sent the last |
8584 |
|
element to some other value than @code{nil}, which you could do, then |
8585 |
You can see this by evaluating the following three expressions in turn. |
you would not have shortened the list.) |
8586 |
First set the value of @code{trees} to @code{(maple oak pine birch)}, |
|
8587 |
then set the @sc{cdr} of its second @sc{cdr} to @code{nil} and then |
You can see shortening by evaluating the following three expressions |
8588 |
find the value of @code{trees}: |
in turn. First set the value of @code{trees} to @code{(maple oak pine |
8589 |
|
birch)}, then set the @sc{cdr} of its second @sc{cdr} to @code{nil} |
8590 |
|
and then find the value of @code{trees}: |
8591 |
|
|
8592 |
@smallexample |
@smallexample |
8593 |
@group |
@group |
8712 |
to learn how lists are implemented in a computer. This will make |
to learn how lists are implemented in a computer. This will make |
8713 |
clear such mysteries as the use of the term `pointer'. |
clear such mysteries as the use of the term `pointer'. |
8714 |
|
|
8715 |
|
@need 1250 |
8716 |
@node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text |
@node cons & search-fwd Review, search Exercises, copy-region-as-kill, Cutting & Storing Text |
8717 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
8718 |
@section Review |
@section Review |
8838 |
@end enumerate |
@end enumerate |
8839 |
|
|
8840 |
@item kill-region |
@item kill-region |
8841 |
@itemx delete-region |
@itemx delete-and-extract-region |
8842 |
@itemx copy-region-as-kill |
@itemx copy-region-as-kill |
8843 |
|
|
8844 |
@code{kill-region} cuts the text between point and mark from the |
@code{kill-region} cuts the text between point and mark from the |
11518 |
@item |
@item |
11519 |
Write a function for Texinfo mode that creates an index entry at the |
Write a function for Texinfo mode that creates an index entry at the |
11520 |
beginning of a paragraph for every @samp{@@dfn} within the paragraph. |
beginning of a paragraph for every @samp{@@dfn} within the paragraph. |
11521 |
(In a Texinfo file, @samp{@@dfn} marks a definition. For more |
(In a Texinfo file, @samp{@@dfn} marks a definition. This book is |
11522 |
information, see |
written in Texinfo.) |
11523 |
|
|
11524 |
|
Many of the functions you will need are described in two of the |
11525 |
|
previous chapters, @ref{Cutting & Storing Text, , Cutting and Storing |
11526 |
|
Text}, and @ref{Yanking, , Yanking Text Back}. If you use |
11527 |
|
@code{forward-paragraph} to put the index entry at the beginning of |
11528 |
|
the paragraph, you will have to use @w{@kbd{C-h f}} |
11529 |
|
(@code{describe-function}) to find out how to make the command go |
11530 |
|
backwards. |
11531 |
|
|
11532 |
|
For more information, see |
11533 |
@ifinfo |
@ifinfo |
11534 |
@ref{Indicating, , Indicating Definitions, texinfo}.) |
@ref{Indicating, , Indicating Definitions, texinfo}. |
11535 |
@end ifinfo |
@end ifinfo |
11536 |
@ifhtml |
@ifhtml |
11537 |
@ref{Indicating, , Indicating, texinfo, Texinfo Manual}.) |
@ref{Indicating, , Indicating, texinfo, Texinfo Manual}, which goes to |
11538 |
|
a Texinfo manual in the current directory. Or, if you are on the |
11539 |
|
Internet, see |
11540 |
|
@uref{http://www.gnu.org/manual/texinfo-4.6/html_node/Indicating.html} |
11541 |
@end ifhtml |
@end ifhtml |
11542 |
@iftex |
@iftex |
11543 |
``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU |
``Indicating Definitions, Commands, etc.'' in @cite{Texinfo, The GNU |
11544 |
Documentation Format}.) |
Documentation Format}. |
11545 |
@end iftex |
@end iftex |
11546 |
@end itemize |
@end itemize |
11547 |
|
|
14713 |
'("../lisp/macros.el" |
'("../lisp/macros.el" |
14714 |
"../lisp/mailalias.el" |
"../lisp/mailalias.el" |
14715 |
"../lisp/makesum.el")) |
"../lisp/makesum.el")) |
14716 |
'< |
'<) |
14717 |
@end group |
@end group |
14718 |
@end smallexample |
@end smallexample |
14719 |
|
|
16105 |
arguments are optional.) |
arguments are optional.) |
16106 |
|
|
16107 |
Each of these arguments consists of a keyword followed by a value. |
Each of these arguments consists of a keyword followed by a value. |
16108 |
Each keyword starts with the character @code{:}. |
Each keyword starts with the colon character @samp{:}. |
16109 |
|
|
16110 |
@need 1250 |
@need 1250 |
16111 |
For example, the customizable user option variable |
For example, the customizable user option variable |
16188 |
those who do not know what they are doing, so they do not |
those who do not know what they are doing, so they do not |
16189 |
inadvertently generate an error. |
inadvertently generate an error. |
16190 |
|
|
16191 |
The @code{custom-set-variables} works somewhat differently than a |
The @code{custom-set-variables} function works somewhat differently |
16192 |
@code{setq}. While I have never learned the differences, I do modify |
than a @code{setq}. While I have never learned the differences, I do |
16193 |
the @code{custom-set-variables} expressions in my @file{.emacs} file |
modify the @code{custom-set-variables} expressions in my @file{.emacs} |
16194 |
by hand: I make the changes in what appears to me to be a reasonable |
file by hand: I make the changes in what appears to me to be a |
16195 |
manner and have not had any problems. Others prefer to use the |
reasonable manner and have not had any problems. Others prefer to use |
16196 |
Customization command and let Emacs do the work for them. |
the Customization command and let Emacs do the work for them. |
16197 |
|
|
16198 |
Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. |
Another @code{custom-set-@dots{}} function is @code{custom-set-faces}. |
16199 |
This function sets the various font faces. Over time, I have set a |
This function sets the various font faces. Over time, I have set a |
16257 |
By now, of course, I remember these things, but when I started, I did |
By now, of course, I remember these things, but when I started, I did |
16258 |
not. |
not. |
16259 |
|
|
16260 |
|
@need 1200 |
16261 |
@smallexample |
@smallexample |
16262 |
@group |
@group |
16263 |
;;;; Bob's .emacs file |
;;;; Bob's .emacs file |
16708 |
Many people in the GNU Emacs community have written extensions to |
Many people in the GNU Emacs community have written extensions to |
16709 |
Emacs. As time goes by, these extensions are often included in new |
Emacs. As time goes by, these extensions are often included in new |
16710 |
releases. For example, the Calendar and Diary packages are now part |
releases. For example, the Calendar and Diary packages are now part |
16711 |
of the standard GNU Emacs. |
of the standard GNU Emacs, as is Calc. |
|
|
|
|
(Calc, which I consider a vital part of Emacs, would be part of the |
|
|
standard distribution except that it was so large it was packaged |
|
|
separately and no one has changed that.) |
|
16712 |
|
|
16713 |
You can use a @code{load} command to evaluate a complete file and |
You can use a @code{load} command to evaluate a complete file and |
16714 |
thereby install all the functions and variables in the file into Emacs. |
thereby install all the functions and variables in the file into Emacs. |
17086 |
(set-mouse-color "white")) |
(set-mouse-color "white")) |
17087 |
@end group |
@end group |
17088 |
@end smallexample |
@end smallexample |
17089 |
|
|
17090 |
|
@item |
17091 |
|
Convert @kbd{@key{CTL}-h} into @key{DEL} and @key{DEL} |
17092 |
|
into @kbd{@key{CTL}-h}.@* |
17093 |
|
(Some olders keyboards needed this, although I have not seen the |
17094 |
|
problem recently.) |
17095 |
|
|
17096 |
|
@smallexample |
17097 |
|
@group |
17098 |
|
;; Translate `C-h' to <DEL>. |
17099 |
|
; (keyboard-translate ?\C-h ?\C-?) |
17100 |
|
|
17101 |
|
;; Translate <DEL> to `C-h'. |
17102 |
|
(keyboard-translate ?\C-? ?\C-h) |
17103 |
|
@end group |
17104 |
|
@end smallexample |
17105 |
|
|
17106 |
|
@item Turn off a blinking cursor! |
17107 |
|
|
17108 |
|
@smallexample |
17109 |
|
@group |
17110 |
|
(if (fboundp 'blink-cursor-mode) |
17111 |
|
(blink-cursor-mode -1)) |
17112 |
|
@end group |
17113 |
|
@end smallexample |
17114 |
|
|
17115 |
|
@item Ignore case when using `grep'@* |
17116 |
|
@samp{-n}@w{ } Prefix each line of output with line number@* |
17117 |
|
@samp{-i}@w{ } Ignore case distinctions@* |
17118 |
|
@samp{-e}@w{ } Protect patterns beginning with a hyphen character, @samp{-} |
17119 |
|
|
17120 |
|
@smallexample |
17121 |
|
(setq grep-command "grep -n -i -e ") |
17122 |
|
@end smallexample |
17123 |
|
|
17124 |
|
@item Automatically uncompress compressed files when visiting them |
17125 |
|
|
17126 |
|
@smallexample |
17127 |
|
(load "uncompress") |
17128 |
|
@end smallexample |
17129 |
|
|
17130 |
|
@item Find an existing buffer, even if it has a different name@* |
17131 |
|
This avoids problems with symbolic links. |
17132 |
|
|
17133 |
|
@smallexample |
17134 |
|
(setq find-file-existing-other-name t) |
17135 |
|
@end smallexample |
17136 |
|
|
17137 |
|
@item Set your language environment and default input method |
17138 |
|
|
17139 |
|
@smallexample |
17140 |
|
@group |
17141 |
|
(set-language-environment "latin-1") |
17142 |
|
;; Remember you can enable or disable multilingual text input |
17143 |
|
;; with the @code{toggle-input-method'} (@kbd{C-\}) command |
17144 |
|
(setq default-input-method "latin-1-prefix") |
17145 |
|
@end group |
17146 |
|
@end smallexample |
17147 |
|
|
17148 |
|
If you want to write with Chinese `GB' characters, set this instead: |
17149 |
|
|
17150 |
|
@smallexample |
17151 |
|
@group |
17152 |
|
(set-language-environment "Chinese-GB") |
17153 |
|
(setq default-input-method "chinese-tonepy") |
17154 |
|
@end group |
17155 |
|
@end smallexample |
17156 |
@end itemize |
@end itemize |
17157 |
|
|
17158 |
|
@subsubheading Fixing Unpleasant Key Bindings |
17159 |
|
@cindex Key bindings, fixing |
17160 |
|
@cindex Bindings, key, fixing unpleasant |
17161 |
|
|
17162 |
|
Some systems bind keys unpleasantly. Sometimes, for example, the |
17163 |
|
@key{CTL} key appears in an awkward spot rather than at the far left |
17164 |
|
of the home row. |
17165 |
|
|
17166 |
|
Usually, when people fix these sorts of keybindings, they do not |
17167 |
|
change their @file{~/.emacs} file. Instead, they bind the proper keys |
17168 |
|
on their consoles with the @code{loadkeys} or @code{install-keymap} |
17169 |
|
commands in their boot script and then include @code{xmodmap} commands |
17170 |
|
in their @file{.xinitrc} or @file{.Xsession} file for X Windows. |
17171 |
|
|
17172 |
|
@need 1250 |
17173 |
|
@noindent |
17174 |
|
For a boot script: |
17175 |
|
|
17176 |
|
@smallexample |
17177 |
|
@group |
17178 |
|
loadkeys /usr/share/keymaps/i386/qwerty/emacs2.kmap.gz |
17179 |
|
|
17180 |
|
@exdent or |
17181 |
|
|
17182 |
|
install-keymap emacs2 |
17183 |
|
@end group |
17184 |
|
@end smallexample |
17185 |
|
|
17186 |
|
@need 1250 |
17187 |
|
@noindent |
17188 |
|
For a @file{.xinitrc} or @file{.Xsession} file when the @key{Caps |
17189 |
|
Lock} key is at the far left of the home row: |
17190 |
|
|
17191 |
|
@smallexample |
17192 |
|
@group |
17193 |
|
# Bind the key labeled `Caps Lock' to `Control' |
17194 |
|
# (Such a broken user interface suggests that keyboard manufacturers |
17195 |
|
# think that computers are typewriters from 1885.) |
17196 |
|
|
17197 |
|
xmodmap -e "clear Lock" |
17198 |
|
xmodmap -e "add Control = Caps_Lock" |
17199 |
|
@end group |
17200 |
|
@end smallexample |
17201 |
|
|
17202 |
|
@need 1250 |
17203 |
|
@noindent |
17204 |
|
In a @file{.xinitrc} or @file{.Xsession} file, to convert an @key{ALT} |
17205 |
|
key to a @key{META} key: |
17206 |
|
|
17207 |
|
@smallexample |
17208 |
|
@group |
17209 |
|
# Some ill designed keyboards have a key labeled ALT and no Meta |
17210 |
|
xmodmap -e "keysym Alt_L = Meta_L Alt_L" |
17211 |
|
@end group |
17212 |
|
@end smallexample |
17213 |
|
|
17214 |
@node Mode Line, , Miscellaneous, Emacs Initialization |
@node Mode Line, , Miscellaneous, Emacs Initialization |
17215 |
@section A Modified Mode Line |
@section A Modified Mode Line |
17216 |
@vindex default-mode-line-format |
@vindex default-mode-line-format |
17288 |
on. However, the format looks complicated because of two features we |
on. However, the format looks complicated because of two features we |
17289 |
have not discussed. |
have not discussed. |
17290 |
|
|
17291 |
|
@cindex Properties, in mode line example |
17292 |
The first string in the mode line is a dash or hyphen, @samp{-}. In |
The first string in the mode line is a dash or hyphen, @samp{-}. In |
17293 |
the old days, it would have been specified simply as @code{"-"}. But |
the old days, it would have been specified simply as @code{"-"}. But |
17294 |
nowadays, Emacs can add properties to a string, such as highlighting |
nowadays, Emacs can add properties to a string, such as highlighting |
17295 |
or, as in this case, a help feature. If you place your mouse cursor |
or, as in this case, a help feature. If you place your mouse cursor |
17296 |
over the hyphen, some help information appears (By default, you must |
over the hyphen, some help information appears (By default, you must |
17297 |
wait one second before the information appears. You can change that |
wait one second before the information appears. You can change that |
17298 |
timing by changing the value of @code{tooltip-delay}.) |
timing by changing the value of @code{tooltip-delay}.) |
17299 |
|
|
17316 |
case, a string. The second, third, and fourth elements of this new |
case, a string. The second, third, and fourth elements of this new |
17317 |
string format can be repeated. |
string format can be repeated. |
17318 |
|
|
17319 |
@xref{Text Props and Strings, , Text Properties in String, elisp, The |
@xref{Text Properties, , Text Properties, elisp, The GNU Emacs Lisp |
17320 |
GNU Emacs Lisp Reference Manual}, and see @ref{Mode Line Format, , Mode |
Reference Manual}, and see @ref{Mode Line Format, , Mode Line Format, |
17321 |
Line Format, elisp, The GNU Emacs Lisp Reference Manual}, for more |
elisp, The GNU Emacs Lisp Reference Manual}, for more information. |
|
information. |
|
17322 |
|
|
17323 |
@code{mode-line-buffer-identification} |
@code{mode-line-buffer-identification} |
17324 |
displays the current buffer name. It is a list |
displays the current buffer name. It is a list |
17623 |
@end group |
@end group |
17624 |
@end smallexample |
@end smallexample |
17625 |
|
|
17626 |
|
@need 1500 |
17627 |
@noindent |
@noindent |
17628 |
Finally, after you type @kbd{d} two more times, Emacs will reach the |
Finally, after you type @kbd{d} two more times, Emacs will reach the |
17629 |
error, and the top two lines of the @file{*Backtrace*} buffer will look |
error, and the top two lines of the @file{*Backtrace*} buffer will look |
17702 |
Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs |
Edebug is described in @ref{edebug, , Edebug, elisp, The GNU Emacs |
17703 |
Lisp Reference Manual}. |
Lisp Reference Manual}. |
17704 |
|
|
17705 |
|
@need 1250 |
17706 |
Here is a bugged function definition for @code{triangle-recursively}. |
Here is a bugged function definition for @code{triangle-recursively}. |
17707 |
@xref{Recursive triangle function, , Recursion in place of a counter}, |
@xref{Recursive triangle function, , Recursion in place of a counter}, |
17708 |
for a review of it. |
for a review of it. |
17790 |
|
|
17791 |
@noindent |
@noindent |
17792 |
This means the value of @code{number} is 3, which is @sc{ascii} |
This means the value of @code{number} is 3, which is @sc{ascii} |
17793 |
`control-c' (the third letter of the alphabet). |
`control-c' (the third letter of the alphabet, in case you need to |
17794 |
|
know this information). |
17795 |
|
|
17796 |
You can continue moving through the code until you reach the line with |
You can continue moving through the code until you reach the line with |
17797 |
the error. Before evaluation, that line looks like this: |
the error. Before evaluation, that line looks like this: |
18121 |
* rotate-yank-pointer:: Move a pointer along a list and around. |
* rotate-yank-pointer:: Move a pointer along a list and around. |
18122 |
* yank:: Paste a copy of a clipped element. |
* yank:: Paste a copy of a clipped element. |
18123 |
* yank-pop:: Insert first element pointed to. |
* yank-pop:: Insert first element pointed to. |
18124 |
|
* ring file:: |
18125 |
@end menu |
@end menu |
18126 |
|
|
18127 |
@node rotate-yank-pointer, yank, Kill Ring, Kill Ring |
@node rotate-yank-pointer, yank, Kill Ring, Kill Ring |
18440 |
@noindent |
@noindent |
18441 |
will be 1. |
will be 1. |
18442 |
|
|
18443 |
|
@need 1200 |
18444 |
Consequently, the argument to @code{nthcdr} will be found as the result of |
Consequently, the argument to @code{nthcdr} will be found as the result of |
18445 |
the expression |
the expression |
18446 |
|
|
18517 |
is 1. (I just checked this by placing the cursor after the expression |
is 1. (I just checked this by placing the cursor after the expression |
18518 |
and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.) |
and typing @kbd{C-x C-e}. Indeed, 1 is printed in the echo area.) |
18519 |
|
|
18520 |
|
@need 2000 |
18521 |
@node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body |
@node rotate-yk-ptr remainder, kill-rng-yk-ptr last elt, Remainder Function, rotate-yk-ptr body |
18522 |
@unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer} |
@unnumberedsubsubsec Using @code{%} in @code{rotate-yank-pointer} |
18523 |
|
|
18816 |
and doing this is easier than writing a function to determine the |
and doing this is easier than writing a function to determine the |
18817 |
magnitude of the number that follows the minus sign. |
magnitude of the number that follows the minus sign. |
18818 |
|
|
18819 |
@node yank-pop, , yank, Kill Ring |
@node yank-pop, ring file, yank, Kill Ring |
18820 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
18821 |
@appendixsec @code{yank-pop} |
@appendixsec @code{yank-pop} |
18822 |
@findex yank-pop |
@findex yank-pop |
18863 |
exchanged so point is again left in front of the newly inserted text. |
exchanged so point is again left in front of the newly inserted text. |
18864 |
That is all there is to it! |
That is all there is to it! |
18865 |
|
|
18866 |
@node Full Graph, GNU Free Documentation License, Kill Ring, Top |
@node ring file, , yank-pop, Kill Ring |
18867 |
|
@comment node-name, next, previous, up |
18868 |
|
@appendixsec The @file{ring.el} File |
18869 |
|
@cindex @file{ring.el} file |
18870 |
|
|
18871 |
|
Interestingly, GNU Emacs posses a file called @file{ring.el} that |
18872 |
|
provides many of the features we just discussed. But functions such |
18873 |
|
as @code{kill-ring-yank-pointer} do not use this library, possibly |
18874 |
|
because they were written earlier. |
18875 |
|
|
18876 |
|
@node Full Graph, Free Software and Free Manuals, Kill Ring, Top |
18877 |
@appendix A Graph with Labelled Axes |
@appendix A Graph with Labelled Axes |
18878 |
|
|
18879 |
Printed axes help you understand a graph. They convey scale. In an |
Printed axes help you understand a graph. They convey scale. In an |
19019 |
@noindent |
@noindent |
19020 |
As we shall see, this expression is not quite right. |
As we shall see, this expression is not quite right. |
19021 |
|
|
19022 |
|
@need 2000 |
19023 |
@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph |
@node print-Y-axis, print-X-axis, print-graph Varlist, Full Graph |
19024 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
19025 |
@appendixsec The @code{print-Y-axis} Function |
@appendixsec The @code{print-Y-axis} Function |
19095 |
divided into several smaller problems. |
divided into several smaller problems. |
19096 |
|
|
19097 |
First, consider the case when the highest value of the graph is an |
First, consider the case when the highest value of the graph is an |
19098 |
integral multiple of five---when it is 5, 10, 15 ,or some higher |
integral multiple of five---when it is 5, 10, 15, or some higher |
19099 |
multiple of five. We can use this value as the Y axis height. |
multiple of five. We can use this value as the Y axis height. |
19100 |
|
|
19101 |
A fairly simply way to determine whether a number is a multiple of |
A fairly simply way to determine whether a number is a multiple of |
19395 |
blank label using the @code{make-string} function. The base line |
blank label using the @code{make-string} function. The base line |
19396 |
consists of the number one followed by a tic mark. |
consists of the number one followed by a tic mark. |
19397 |
|
|
19398 |
|
@need 2000 |
19399 |
@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis |
@node print-Y-axis Penultimate, , Y-axis-column, print-Y-axis |
19400 |
@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} |
@appendixsubsec The Not Quite Final Version of @code{print-Y-axis} |
19401 |
|
|
19471 |
will pass the value of @code{height-of-top-line}, which |
will pass the value of @code{height-of-top-line}, which |
19472 |
in this case would end up as 15.) |
in this case would end up as 15.) |
19473 |
|
|
19474 |
|
@need 2000 |
19475 |
@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph |
@node print-X-axis, Print Whole Graph, print-Y-axis, Full Graph |
19476 |
@appendixsec The @code{print-X-axis} Function |
@appendixsec The @code{print-X-axis} Function |
19477 |
@cindex Axis, print horizontal |
@cindex Axis, print horizontal |
19814 |
|
|
19815 |
@need 1250 |
@need 1250 |
19816 |
Emacs will print the horizontal axis like this: |
Emacs will print the horizontal axis like this: |
19817 |
|
@sp 1 |
19818 |
|
|
19819 |
@smallexample |
@smallexample |
19820 |
@group |
@group |
20069 |
@end group |
@end group |
20070 |
@end smallexample |
@end smallexample |
20071 |
|
|
20072 |
|
@need 1200 |
20073 |
On the other hand, if you pass @code{print-graph} a |
On the other hand, if you pass @code{print-graph} a |
20074 |
@code{vertical-step} value of 2, by evaluating this expression: |
@code{vertical-step} value of 2, by evaluating this expression: |
20075 |
|
|
20153 |
@end smallexample |
@end smallexample |
20154 |
|
|
20155 |
@noindent |
@noindent |
20156 |
On my machine, this takes about an hour. It looks though 303 Lisp |
On my old machine, this took about an hour. It looked though 303 Lisp |
20157 |
files in my copy of Emacs version 19.23. After all that computing, |
files in my copy of Emacs version 19.23. After all that computing, |
20158 |
the @code{list-for-graph} has this value: |
the @code{list-for-graph} had this value: |
20159 |
|
|
20160 |
@smallexample |
@smallexample |
20161 |
@group |
@group |
20165 |
@end smallexample |
@end smallexample |
20166 |
|
|
20167 |
@noindent |
@noindent |
20168 |
This means that my copy of Emacs has 537 function definitions with |
This means that my copy of Emacs had 537 function definitions with |
20169 |
fewer than 10 words or symbols in them, 1,027 function definitions |
fewer than 10 words or symbols in them, 1,027 function definitions |
20170 |
with 10 to 19 words or symbols in them, 955 function definitions with |
with 10 to 19 words or symbols in them, 955 function definitions with |
20171 |
20 to 29 words or symbols in them, and so on. |
20 to 29 words or symbols in them, and so on. |
20213 |
is a function definition that says `return the value resulting from |
is a function definition that says `return the value resulting from |
20214 |
dividing whatever is passed to me as @code{arg} by 50'. |
dividing whatever is passed to me as @code{arg} by 50'. |
20215 |
|
|
20216 |
|
@need 1200 |
20217 |
Earlier, for example, we had a function @code{multiply-by-seven}; it |
Earlier, for example, we had a function @code{multiply-by-seven}; it |
20218 |
multiplied its argument by 7. This function is similar, except it |
multiplied its argument by 7. This function is similar, except it |
20219 |
divides its argument by 50; and, it has no name. The anonymous |
divides its argument by 50; and, it has no name. The anonymous |
21142 |
|
|
21143 |
When made and installed, you can call the @code{print-graph} command |
When made and installed, you can call the @code{print-graph} command |
21144 |
like this: |
like this: |
21145 |
|
@sp 1 |
21146 |
|
|
21147 |
@smallexample |
@smallexample |
21148 |
@group |
@group |
21149 |
(print-graph fiftieth-list-for-graph 50 10) |
(print-graph fiftieth-list-for-graph 50 10) |
21150 |
@end group |
@end group |
21151 |
@end smallexample |
@end smallexample |
21152 |
|
@sp 1 |
21153 |
|
|
21154 |
|
@noindent |
21155 |
Here is the graph: |
Here is the graph: |
|
|
|
21156 |
@sp 2 |
@sp 2 |
21157 |
|
|
21158 |
@smallexample |
@smallexample |
21184 |
|
|
21185 |
@sp 2 |
@sp 2 |
21186 |
|
|
21187 |
|
@noindent |
21188 |
The largest group of functions contain 10 -- 19 words and symbols each. |
The largest group of functions contain 10 -- 19 words and symbols each. |
21189 |
|
|
21190 |
@node GNU Free Documentation License, Index, Full Graph, Top |
@node Free Software and Free Manuals, GNU Free Documentation License, Full Graph, Top |
21191 |
|
@appendix Free Software and Free Manuals |
21192 |
|
|
21193 |
|
@strong{by Richard M. Stallman} |
21194 |
|
@sp 1 |
21195 |
|
|
21196 |
|
The biggest deficiency in free operating systems is not in the |
21197 |
|
software---it is the lack of good free manuals that we can include in |
21198 |
|
these systems. Many of our most important programs do not come with |
21199 |
|
full manuals. Documentation is an essential part of any software |
21200 |
|
package; when an important free software package does not come with a |
21201 |
|
free manual, that is a major gap. We have many such gaps today. |
21202 |
|
|
21203 |
|
Once upon a time, many years ago, I thought I would learn Perl. I got |
21204 |
|
a copy of a free manual, but I found it hard to read. When I asked |
21205 |
|
Perl users about alternatives, they told me that there were better |
21206 |
|
introductory manuals---but those were not free. |
21207 |
|
|
21208 |
|
Why was this? The authors of the good manuals had written them for |
21209 |
|
O'Reilly Associates, which published them with restrictive terms---no |
21210 |
|
copying, no modification, source files not available---which exclude |
21211 |
|
them from the free software community. |
21212 |
|
|
21213 |
|
That wasn't the first time this sort of thing has happened, and (to |
21214 |
|
our community's great loss) it was far from the last. Proprietary |
21215 |
|
manual publishers have enticed a great many authors to restrict their |
21216 |
|
manuals since then. Many times I have heard a GNU user eagerly tell me |
21217 |
|
about a manual that he is writing, with which he expects to help the |
21218 |
|
GNU project---and then had my hopes dashed, as he proceeded to explain |
21219 |
|
that he had signed a contract with a publisher that would restrict it |
21220 |
|
so that we cannot use it. |
21221 |
|
|
21222 |
|
Given that writing good English is a rare skill among programmers, we |
21223 |
|
can ill afford to lose manuals this way. |
21224 |
|
|
21225 |
|
@c (texinfo)uref |
21226 |
|
(The Free Software Foundation |
21227 |
|
@uref{http://www.gnu.org/doc/doc.html#DescriptionsOfGNUDocumentation, , |
21228 |
|
sells printed copies} of free @uref{http://www.gnu.org/doc/doc.html, |
21229 |
|
GNU manuals}, too.) |
21230 |
|
|
21231 |
|
Free documentation, like free software, is a matter of freedom, not |
21232 |
|
price. The problem with these manuals was not that O'Reilly Associates |
21233 |
|
charged a price for printed copies---that in itself is fine. (The Free |
21234 |
|
Software Foundation sells printed copies of free GNU manuals, too.) |
21235 |
|
But GNU manuals are available in source code form, while these manuals |
21236 |
|
are available only on paper. GNU manuals come with permission to copy |
21237 |
|
and modify; the Perl manuals do not. These restrictions are the |
21238 |
|
problems. |
21239 |
|
|
21240 |
|
The criterion for a free manual is pretty much the same as for free |
21241 |
|
software: it is a matter of giving all users certain |
21242 |
|
freedoms. Redistribution (including commercial redistribution) must be |
21243 |
|
permitted, so that the manual can accompany every copy of the program, |
21244 |
|
on-line or on paper. Permission for modification is crucial too. |
21245 |
|
|
21246 |
|
As a general rule, I don't believe that it is essential for people to |
21247 |
|
have permission to modify all sorts of articles and books. The issues |
21248 |
|
for writings are not necessarily the same as those for software. For |
21249 |
|
example, I don't think you or I are obliged to give permission to |
21250 |
|
modify articles like this one, which describe our actions and our |
21251 |
|
views. |
21252 |
|
|
21253 |
|
But there is a particular reason why the freedom to modify is crucial |
21254 |
|
for documentation for free software. When people exercise their right |
21255 |
|
to modify the software, and add or change its features, if they are |
21256 |
|
conscientious they will change the manual too---so they can provide |
21257 |
|
accurate and usable documentation with the modified program. A manual |
21258 |
|
which forbids programmers to be conscientious and finish the job, or |
21259 |
|
more precisely requires them to write a new manual from scratch if |
21260 |
|
they change the program, does not fill our community's needs. |
21261 |
|
|
21262 |
|
While a blanket prohibition on modification is unacceptable, some |
21263 |
|
kinds of limits on the method of modification pose no problem. For |
21264 |
|
example, requirements to preserve the original author's copyright |
21265 |
|
notice, the distribution terms, or the list of authors, are ok. It is |
21266 |
|
also no problem to require modified versions to include notice that |
21267 |
|
they were modified, even to have entire sections that may not be |
21268 |
|
deleted or changed, as long as these sections deal with nontechnical |
21269 |
|
topics. (Some GNU manuals have them.) |
21270 |
|
|
21271 |
|
These kinds of restrictions are not a problem because, as a practical |
21272 |
|
matter, they don't stop the conscientious programmer from adapting the |
21273 |
|
manual to fit the modified program. In other words, they don't block |
21274 |
|
the free software community from making full use of the manual. |
21275 |
|
|
21276 |
|
However, it must be possible to modify all the technical content of |
21277 |
|
the manual, and then distribute the result in all the usual media, |
21278 |
|
through all the usual channels; otherwise, the restrictions do block |
21279 |
|
the community, the manual is not free, and so we need another manual. |
21280 |
|
|
21281 |
|
Unfortunately, it is often hard to find someone to write another |
21282 |
|
manual when a proprietary manual exists. The obstacle is that many |
21283 |
|
users think that a proprietary manual is good enough---so they don't |
21284 |
|
see the need to write a free manual. They do not see that the free |
21285 |
|
operating system has a gap that needs filling. |
21286 |
|
|
21287 |
|
Why do users think that proprietary manuals are good enough? Some have |
21288 |
|
not considered the issue. I hope this article will do something to |
21289 |
|
change that. |
21290 |
|
|
21291 |
|
Other users consider proprietary manuals acceptable for the same |
21292 |
|
reason so many people consider proprietary software acceptable: they |
21293 |
|
judge in purely practical terms, not using freedom as a |
21294 |
|
criterion. These people are entitled to their opinions, but since |
21295 |
|
those opinions spring from values which do not include freedom, they |
21296 |
|
are no guide for those of us who do value freedom. |
21297 |
|
|
21298 |
|
Please spread the word about this issue. We continue to lose manuals |
21299 |
|
to proprietary publishing. If we spread the word that proprietary |
21300 |
|
manuals are not sufficient, perhaps the next person who wants to help |
21301 |
|
GNU by writing documentation will realize, before it is too late, that |
21302 |
|
he must above all make it free. |
21303 |
|
|
21304 |
|
We can also encourage commercial publishers to sell free, copylefted |
21305 |
|
manuals instead of proprietary ones. One way you can help this is to |
21306 |
|
check the distribution terms of a manual before you buy it, and prefer |
21307 |
|
copylefted manuals to non-copylefted ones. |
21308 |
|
|
21309 |
|
@sp 2 |
21310 |
|
@noindent |
21311 |
|
Note: The Free Software Foundation maintains a page on its Web site |
21312 |
|
that lists free books available from other publishers:@* |
21313 |
|
@uref{http://www.gnu.org/doc/other-free-books.html} |
21314 |
|
|
21315 |
|
|
21316 |
|
@node GNU Free Documentation License, Index, Free Software and Free Manuals, Top |
21317 |
@appendix GNU Free Documentation License |
@appendix GNU Free Documentation License |
21318 |
|
|
21319 |
@cindex FDL, GNU Free Documentation License |
@cindex FDL, GNU Free Documentation License |
21320 |
@center Version 1.1, March 2000 |
@center Version 1.2, November 2002 |
21321 |
|
|
21322 |
@display |
@display |
21323 |
Copyright @copyright{} 2000 Free Software Foundation, Inc. |
Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. |
21324 |
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA |
21325 |
|
|
21326 |
Everyone is permitted to copy and distribute verbatim copies |
Everyone is permitted to copy and distribute verbatim copies |
21332 |
PREAMBLE |
PREAMBLE |
21333 |
|
|
21334 |
The purpose of this License is to make a manual, textbook, or other |
The purpose of this License is to make a manual, textbook, or other |
21335 |
written document @dfn{free} in the sense of freedom: to assure everyone |
functional and useful document @dfn{free} in the sense of freedom: to |
21336 |
the effective freedom to copy and redistribute it, with or without |
assure everyone the effective freedom to copy and redistribute it, |
21337 |
modifying it, either commercially or noncommercially. Secondarily, |
with or without modifying it, either commercially or noncommercially. |
21338 |
this License preserves for the author and publisher a way to get |
Secondarily, this License preserves for the author and publisher a way |
21339 |
credit for their work, while not being considered responsible for |
to get credit for their work, while not being considered responsible |
21340 |
modifications made by others. |
for modifications made by others. |
21341 |
|
|
21342 |
This License is a kind of ``copyleft'', which means that derivative |
This License is a kind of ``copyleft'', which means that derivative |
21343 |
works of the document must themselves be free in the same sense. It |
works of the document must themselves be free in the same sense. It |
21355 |
@item |
@item |
21356 |
APPLICABILITY AND DEFINITIONS |
APPLICABILITY AND DEFINITIONS |
21357 |
|
|
21358 |
This License applies to any manual or other work that contains a |
This License applies to any manual or other work, in any medium, that |
21359 |
notice placed by the copyright holder saying it can be distributed |
contains a notice placed by the copyright holder saying it can be |
21360 |
under the terms of this License. The ``Document'', below, refers to any |
distributed under the terms of this License. Such a notice grants a |
21361 |
such manual or work. Any member of the public is a licensee, and is |
world-wide, royalty-free license, unlimited in duration, to use that |
21362 |
addressed as ``you''. |
work under the conditions stated herein. The ``Document'', below, |
21363 |
|
refers to any such manual or work. Any member of the public is a |
21364 |
|
licensee, and is addressed as ``you''. You accept the license if you |
21365 |
|
copy, modify or distribute the work in a way requiring permission |
21366 |
|
under copyright law. |
21367 |
|
|
21368 |
A ``Modified Version'' of the Document means any work containing the |
A ``Modified Version'' of the Document means any work containing the |
21369 |
Document or a portion of it, either copied verbatim, or with |
Document or a portion of it, either copied verbatim, or with |
21370 |
modifications and/or translated into another language. |
modifications and/or translated into another language. |
21371 |
|
|
21372 |
A ``Secondary Section'' is a named appendix or a front-matter section of |
A ``Secondary Section'' is a named appendix or a front-matter section |
21373 |
the Document that deals exclusively with the relationship of the |
of the Document that deals exclusively with the relationship of the |
21374 |
publishers or authors of the Document to the Document's overall subject |
publishers or authors of the Document to the Document's overall |
21375 |
(or to related matters) and contains nothing that could fall directly |
subject (or to related matters) and contains nothing that could fall |
21376 |
within that overall subject. (For example, if the Document is in part a |
directly within that overall subject. (Thus, if the Document is in |
21377 |
textbook of mathematics, a Secondary Section may not explain any |
part a textbook of mathematics, a Secondary Section may not explain |
21378 |
mathematics.) The relationship could be a matter of historical |
any mathematics.) The relationship could be a matter of historical |
21379 |
connection with the subject or with related matters, or of legal, |
connection with the subject or with related matters, or of legal, |
21380 |
commercial, philosophical, ethical or political position regarding |
commercial, philosophical, ethical or political position regarding |
21381 |
them. |
them. |
21382 |
|
|
21383 |
The ``Invariant Sections'' are certain Secondary Sections whose titles |
The ``Invariant Sections'' are certain Secondary Sections whose titles |
21384 |
are designated, as being those of Invariant Sections, in the notice |
are designated, as being those of Invariant Sections, in the notice |
21385 |
that says that the Document is released under this License. |
that says that the Document is released under this License. If a |
21386 |
|
section does not fit the above definition of Secondary then it is not |
21387 |
|
allowed to be designated as Invariant. The Document may contain zero |
21388 |
|
Invariant Sections. If the Document does not identify any Invariant |
21389 |
|
Sections then there are none. |
21390 |
|
|
21391 |
The ``Cover Texts'' are certain short passages of text that are listed, |
The ``Cover Texts'' are certain short passages of text that are listed, |
21392 |
as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
as Front-Cover Texts or Back-Cover Texts, in the notice that says that |
21393 |
the Document is released under this License. |
the Document is released under this License. A Front-Cover Text may |
21394 |
|
be at most 5 words, and a Back-Cover Text may be at most 25 words. |
21395 |
|
|
21396 |
A ``Transparent'' copy of the Document means a machine-readable copy, |
A ``Transparent'' copy of the Document means a machine-readable copy, |
21397 |
represented in a format whose specification is available to the |
represented in a format whose specification is available to the |
21398 |
general public, whose contents can be viewed and edited directly and |
general public, that is suitable for revising the document |
21399 |
straightforwardly with generic text editors or (for images composed of |
straightforwardly with generic text editors or (for images composed of |
21400 |
pixels) generic paint programs or (for drawings) some widely available |
pixels) generic paint programs or (for drawings) some widely available |
21401 |
drawing editor, and that is suitable for input to text formatters or |
drawing editor, and that is suitable for input to text formatters or |
21402 |
for automatic translation to a variety of formats suitable for input |
for automatic translation to a variety of formats suitable for input |
21403 |
to text formatters. A copy made in an otherwise Transparent file |
to text formatters. A copy made in an otherwise Transparent file |
21404 |
format whose markup has been designed to thwart or discourage |
format whose markup, or absence of markup, has been arranged to thwart |
21405 |
subsequent modification by readers is not Transparent. A copy that is |
or discourage subsequent modification by readers is not Transparent. |
21406 |
not ``Transparent'' is called ``Opaque''. |
An image format is not Transparent if used for any substantial amount |
21407 |
|
of text. A copy that is not ``Transparent'' is called ``Opaque''. |
21408 |
|
|
21409 |
Examples of suitable formats for Transparent copies include plain |
Examples of suitable formats for Transparent copies include plain |
21410 |
@sc{ascii} without markup, Texinfo input format, La@TeX{} input format, |
@sc{ascii} without markup, Texinfo input format, La@TeX{} input |
21411 |
@acronym{SGML} or @acronym{XML} using a publicly available |
format, @acronym{SGML} or @acronym{XML} using a publicly available |
21412 |
@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed |
@acronym{DTD}, and standard-conforming simple @acronym{HTML}, |
21413 |
for human modification. Opaque formats include PostScript, |
PostScript or @acronym{PDF} designed for human modification. Examples |
21414 |
@acronym{PDF}, proprietary formats that can be read and edited only by |
of transparent image formats include @acronym{PNG}, @acronym{XCF} and |
21415 |
proprietary word processors, @acronym{SGML} or @acronym{XML} for which |
@acronym{JPG}. Opaque formats include proprietary formats that can be |
21416 |
the @acronym{DTD} and/or processing tools are not generally available, |
read and edited only by proprietary word processors, @acronym{SGML} or |
21417 |
and the machine-generated @acronym{HTML} produced by some word |
@acronym{XML} for which the @acronym{DTD} and/or processing tools are |
21418 |
processors for output purposes only. |
not generally available, and the machine-generated @acronym{HTML}, |
21419 |
|
PostScript or @acronym{PDF} produced by some word processors for |
21420 |
|
output purposes only. |
21421 |
|
|
21422 |
The ``Title Page'' means, for a printed book, the title page itself, |
The ``Title Page'' means, for a printed book, the title page itself, |
21423 |
plus such following pages as are needed to hold, legibly, the material |
plus such following pages as are needed to hold, legibly, the material |
21426 |
the text near the most prominent appearance of the work's title, |
the text near the most prominent appearance of the work's title, |
21427 |
preceding the beginning of the body of the text. |
preceding the beginning of the body of the text. |
21428 |
|
|
21429 |
|
A section ``Entitled XYZ'' means a named subunit of the Document whose |
21430 |
|
title either is precisely XYZ or contains XYZ in parentheses following |
21431 |
|
text that translates XYZ in another language. (Here XYZ stands for a |
21432 |
|
specific section name mentioned below, such as ``Acknowledgements'', |
21433 |
|
``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' |
21434 |
|
of such a section when you modify the Document means that it remains a |
21435 |
|
section ``Entitled XYZ'' according to this definition. |
21436 |
|
|
21437 |
|
The Document may include Warranty Disclaimers next to the notice which |
21438 |
|
states that this License applies to the Document. These Warranty |
21439 |
|
Disclaimers are considered to be included by reference in this |
21440 |
|
License, but only as regards disclaiming warranties: any other |
21441 |
|
implication that these Warranty Disclaimers may have is void and has |
21442 |
|
no effect on the meaning of this License. |
21443 |
|
|
21444 |
@item |
@item |
21445 |
VERBATIM COPYING |
VERBATIM COPYING |
21446 |
|
|
21460 |
@item |
@item |
21461 |
COPYING IN QUANTITY |
COPYING IN QUANTITY |
21462 |
|
|
21463 |
If you publish printed copies of the Document numbering more than 100, |
If you publish printed copies (or copies in media that commonly have |
21464 |
and the Document's license notice requires Cover Texts, you must enclose |
printed covers) of the Document, numbering more than 100, and the |
21465 |
the copies in covers that carry, clearly and legibly, all these Cover |
Document's license notice requires Cover Texts, you must enclose the |
21466 |
|
copies in covers that carry, clearly and legibly, all these Cover |
21467 |
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on |
21468 |
the back cover. Both covers must also clearly and legibly identify |
the back cover. Both covers must also clearly and legibly identify |
21469 |
you as the publisher of these copies. The front cover must present |
you as the publisher of these copies. The front cover must present |
21481 |
If you publish or distribute Opaque copies of the Document numbering |
If you publish or distribute Opaque copies of the Document numbering |
21482 |
more than 100, you must either include a machine-readable Transparent |
more than 100, you must either include a machine-readable Transparent |
21483 |
copy along with each Opaque copy, or state in or with each Opaque copy |
copy along with each Opaque copy, or state in or with each Opaque copy |
21484 |
a publicly-accessible computer-network location containing a complete |
a computer-network location from which the general network-using |
21485 |
Transparent copy of the Document, free of added material, which the |
public has access to download using public-standard network protocols |
21486 |
general network-using public has access to download anonymously at no |
a complete Transparent copy of the Document, free of added material. |
21487 |
charge using public-standard network protocols. If you use the latter |
If you use the latter option, you must take reasonably prudent steps, |
21488 |
option, you must take reasonably prudent steps, when you begin |
when you begin distribution of Opaque copies in quantity, to ensure |
21489 |
distribution of Opaque copies in quantity, to ensure that this |
that this Transparent copy will remain thus accessible at the stated |
21490 |
Transparent copy will remain thus accessible at the stated location |
location until at least one year after the last time you distribute an |
21491 |
until at least one year after the last time you distribute an Opaque |
Opaque copy (directly or through your agents or retailers) of that |
21492 |
copy (directly or through your agents or retailers) of that edition to |
edition to the public. |
|
the public. |
|
21493 |
|
|
21494 |
It is requested, but not required, that you contact the authors of the |
It is requested, but not required, that you contact the authors of the |
21495 |
Document well before redistributing any large number of copies, to give |
Document well before redistributing any large number of copies, to give |
21517 |
List on the Title Page, as authors, one or more persons or entities |
List on the Title Page, as authors, one or more persons or entities |
21518 |
responsible for authorship of the modifications in the Modified |
responsible for authorship of the modifications in the Modified |
21519 |
Version, together with at least five of the principal authors of the |
Version, together with at least five of the principal authors of the |
21520 |
Document (all of its principal authors, if it has less than five). |
Document (all of its principal authors, if it has fewer than five), |
21521 |
|
unless they release you from this requirement. |
21522 |
|
|
21523 |
@item |
@item |
21524 |
State on the Title page the name of the publisher of the |
State on the Title page the name of the publisher of the |
21544 |
Include an unaltered copy of this License. |
Include an unaltered copy of this License. |
21545 |
|
|
21546 |
@item |
@item |
21547 |
Preserve the section entitled ``History'', and its title, and add to |
Preserve the section Entitled ``History'', Preserve its Title, and add |
21548 |
it an item stating at least the title, year, new authors, and |
to it an item stating at least the title, year, new authors, and |
21549 |
publisher of the Modified Version as given on the Title Page. If |
publisher of the Modified Version as given on the Title Page. If |
21550 |
there is no section entitled ``History'' in the Document, create one |
there is no section Entitled ``History'' in the Document, create one |
21551 |
stating the title, year, authors, and publisher of the Document as |
stating the title, year, authors, and publisher of the Document as |
21552 |
given on its Title Page, then add an item describing the Modified |
given on its Title Page, then add an item describing the Modified |
21553 |
Version as stated in the previous sentence. |
Version as stated in the previous sentence. |
21562 |
publisher of the version it refers to gives permission. |
publisher of the version it refers to gives permission. |
21563 |
|
|
21564 |
@item |
@item |
21565 |
In any section entitled ``Acknowledgments'' or ``Dedications'', |
For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve |
21566 |
preserve the section's title, and preserve in the section all the |
the Title of the section, and preserve in the section all the |
21567 |
substance and tone of each of the contributor acknowledgments |
substance and tone of each of the contributor acknowledgements and/or |
21568 |
and/or dedications given therein. |
dedications given therein. |
21569 |
|
|
21570 |
@item |
@item |
21571 |
Preserve all the Invariant Sections of the Document, |
Preserve all the Invariant Sections of the Document, |
21573 |
or the equivalent are not considered part of the section titles. |
or the equivalent are not considered part of the section titles. |
21574 |
|
|
21575 |
@item |
@item |
21576 |
Delete any section entitled ``Endorsements''. Such a section |
Delete any section Entitled ``Endorsements''. Such a section |
21577 |
may not be included in the Modified Version. |
may not be included in the Modified Version. |
21578 |
|
|
21579 |
@item |
@item |
21580 |
Do not retitle any existing section as ``Endorsements'' |
Do not retitle any existing section to be Entitled ``Endorsements'' or |
21581 |
or to conflict in title with any Invariant Section. |
to conflict in title with any Invariant Section. |
21582 |
|
|
21583 |
|
@item |
21584 |
|
Preserve any Warranty Disclaimers. |
21585 |
@end enumerate |
@end enumerate |
21586 |
|
|
21587 |
If the Modified Version includes new front-matter sections or |
If the Modified Version includes new front-matter sections or |
21591 |
list of Invariant Sections in the Modified Version's license notice. |
list of Invariant Sections in the Modified Version's license notice. |
21592 |
These titles must be distinct from any other section titles. |
These titles must be distinct from any other section titles. |
21593 |
|
|
21594 |
You may add a section entitled ``Endorsements'', provided it contains |
You may add a section Entitled ``Endorsements'', provided it contains |
21595 |
nothing but endorsements of your Modified Version by various |
nothing but endorsements of your Modified Version by various |
21596 |
parties---for example, statements of peer review or that the text has |
parties---for example, statements of peer review or that the text has |
21597 |
been approved by an organization as the authoritative definition of a |
been approved by an organization as the authoritative definition of a |
21619 |
versions, provided that you include in the combination all of the |
versions, provided that you include in the combination all of the |
21620 |
Invariant Sections of all of the original documents, unmodified, and |
Invariant Sections of all of the original documents, unmodified, and |
21621 |
list them all as Invariant Sections of your combined work in its |
list them all as Invariant Sections of your combined work in its |
21622 |
license notice. |
license notice, and that you preserve all their Warranty Disclaimers. |
21623 |
|
|
21624 |
The combined work need only contain one copy of this License, and |
The combined work need only contain one copy of this License, and |
21625 |
multiple identical Invariant Sections may be replaced with a single |
multiple identical Invariant Sections may be replaced with a single |
21630 |
Make the same adjustment to the section titles in the list of |
Make the same adjustment to the section titles in the list of |
21631 |
Invariant Sections in the license notice of the combined work. |
Invariant Sections in the license notice of the combined work. |
21632 |
|
|
21633 |
In the combination, you must combine any sections entitled ``History'' |
In the combination, you must combine any sections Entitled ``History'' |
21634 |
in the various original documents, forming one section entitled |
in the various original documents, forming one section Entitled |
21635 |
``History''; likewise combine any sections entitled ``Acknowledgments'', |
``History''; likewise combine any sections Entitled ``Acknowledgements'', |
21636 |
and any sections entitled ``Dedications''. You must delete all sections |
and any sections Entitled ``Dedications''. You must delete all |
21637 |
entitled ``Endorsements.'' |
sections Entitled ``Endorsements.'' |
21638 |
|
|
21639 |
@item |
@item |
21640 |
COLLECTIONS OF DOCUMENTS |
COLLECTIONS OF DOCUMENTS |
21655 |
|
|
21656 |
A compilation of the Document or its derivatives with other separate |
A compilation of the Document or its derivatives with other separate |
21657 |
and independent documents or works, in or on a volume of a storage or |
and independent documents or works, in or on a volume of a storage or |
21658 |
distribution medium, does not as a whole count as a Modified Version |
distribution medium, is called an ``aggregate'' if the copyright |
21659 |
of the Document, provided no compilation copyright is claimed for the |
resulting from the compilation is not used to limit the legal rights |
21660 |
compilation. Such a compilation is called an ``aggregate'', and this |
of the compilation's users beyond what the individual works permit. |
21661 |
License does not apply to the other self-contained works thus compiled |
When the Document is included in an aggregate, this License does not |
21662 |
with the Document, on account of their being thus compiled, if they |
apply to the other works in the aggregate which are not themselves |
21663 |
are not themselves derivative works of the Document. |
derivative works of the Document. |
21664 |
|
|
21665 |
If the Cover Text requirement of section 3 is applicable to these |
If the Cover Text requirement of section 3 is applicable to these |
21666 |
copies of the Document, then if the Document is less than one quarter |
copies of the Document, then if the Document is less than one half of |
21667 |
of the entire aggregate, the Document's Cover Texts may be placed on |
the entire aggregate, the Document's Cover Texts may be placed on |
21668 |
covers that surround only the Document within the aggregate. |
covers that bracket the Document within the aggregate, or the |
21669 |
Otherwise they must appear on covers around the whole aggregate. |
electronic equivalent of covers if the Document is in electronic form. |
21670 |
|
Otherwise they must appear on printed covers that bracket the whole |
21671 |
|
aggregate. |
21672 |
|
|
21673 |
@item |
@item |
21674 |
TRANSLATION |
TRANSLATION |
21679 |
permission from their copyright holders, but you may include |
permission from their copyright holders, but you may include |
21680 |
translations of some or all Invariant Sections in addition to the |
translations of some or all Invariant Sections in addition to the |
21681 |
original versions of these Invariant Sections. You may include a |
original versions of these Invariant Sections. You may include a |
21682 |
translation of this License provided that you also include the |
translation of this License, and all the license notices in the |
21683 |
original English version of this License. In case of a disagreement |
Document, and any Warranty Disclaimers, provided that you also include |
21684 |
between the translation and the original English version of this |
the original English version of this License and the original versions |
21685 |
License, the original English version will prevail. |
of those notices and disclaimers. In case of a disagreement between |
21686 |
|
the translation and the original version of this License or a notice |
21687 |
|
or disclaimer, the original version will prevail. |
21688 |
|
|
21689 |
|
If a section in the Document is Entitled ``Acknowledgements'', |
21690 |
|
``Dedications'', or ``History'', the requirement (section 4) to Preserve |
21691 |
|
its Title (section 1) will typically require changing the actual |
21692 |
|
title. |
21693 |
|
|
21694 |
@item |
@item |
21695 |
TERMINATION |
TERMINATION |
21721 |
as a draft) by the Free Software Foundation. |
as a draft) by the Free Software Foundation. |
21722 |
@end enumerate |
@end enumerate |
21723 |
|
|
21724 |
|
@page |
21725 |
|
@appendixsubsec ADDENDUM: How to use this License for your documents |
21726 |
|
|
21727 |
|
To use this License in a document you have written, include a copy of |
21728 |
|
the License in the document and put the following copyright and |
21729 |
|
license notices just after the title page: |
21730 |
|
|
21731 |
|
@smallexample |
21732 |
|
@group |
21733 |
|
Copyright (C) @var{year} @var{your name}. |
21734 |
|
Permission is granted to copy, distribute and/or modify this document |
21735 |
|
under the terms of the GNU Free Documentation License, Version 1.2 |
21736 |
|
or any later version published by the Free Software Foundation; |
21737 |
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. |
21738 |
|
A copy of the license is included in the section entitled ``GNU |
21739 |
|
Free Documentation License''. |
21740 |
|
@end group |
21741 |
|
@end smallexample |
21742 |
|
|
21743 |
|
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, |
21744 |
|
replace the ``with...Texts.'' line with this: |
21745 |
|
|
21746 |
|
@smallexample |
21747 |
|
@group |
21748 |
|
with the Invariant Sections being @var{list their titles}, with |
21749 |
|
the Front-Cover Texts being @var{list}, and with the Back-Cover Texts |
21750 |
|
being @var{list}. |
21751 |
|
@end group |
21752 |
|
@end smallexample |
21753 |
|
|
21754 |
|
If you have Invariant Sections without Cover Texts, or some other |
21755 |
|
combination of the three, merge those two alternatives to suit the |
21756 |
|
situation. |
21757 |
|
|
21758 |
|
If your document contains nontrivial examples of program code, we |
21759 |
|
recommend releasing these examples in parallel under your choice of |
21760 |
|
free software license, such as the GNU General Public License, |
21761 |
|
to permit their use in free software. |
21762 |
|
|
21763 |
@node Index, About the Author, GNU Free Documentation License, Top |
@node Index, About the Author, GNU Free Documentation License, Top |
21764 |
@comment node-name, next, previous, up |
@comment node-name, next, previous, up |
21765 |
@unnumbered Index |
@unnumbered Index |
21831 |
@end iftex |
@end iftex |
21832 |
|
|
21833 |
@bye |
@bye |
21834 |
|
|
21835 |
|
@ignore |
21836 |
|
arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf |
21837 |
|
@end ignore |