/[emacs]/emacs/lispintro/emacs-lisp-intro.texi
ViewVC logotype

Diff of /emacs/lispintro/emacs-lisp-intro.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.15.2.1 by miles, Fri Apr 4 06:20:40 2003 UTC revision 1.15.2.2 by miles, Tue Oct 14 23:10:12 2003 UTC
# Line 1  Line 1 
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
# Line 13  Line 13 
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
# Line 21  Line 21 
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:
# Line 48  Line 48 
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 ================
# Line 144  Line 155 
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 ----------------------------------------------------
# Line 225  Line 172 
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    
# Line 269  Free Software Foundation raise funds for Line 236  Free Software Foundation raise funds for
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    
# Line 285  Free Software Foundation raise funds for Line 252  Free Software Foundation raise funds for
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
# Line 360  every node in every chapter. Line 298  every node in every chapter.
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::
# Line 779  Handling the Kill Ring Line 718  Handling the Kill Ring
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    
# Line 832  Printing the Whole Graph Line 772  Printing the Whole Graph
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
# Line 1090  Robert J. Chassell Line 1040  Robert J. Chassell
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
# Line 1542  carry out.  Instead, the symbol is used, Line 1492  carry out.  Instead, the symbol is used,
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
# Line 2008  kind of information it uses.  The argume Line 1958  kind of information it uses.  The argume
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.
# Line 2324  for @samp{%s}: Line 2275  for @samp{%s}:
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)
# Line 2536  Learning Lisp is like climbing a hill in Line 2487  Learning Lisp is like climbing a hill in
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
# Line 3535  each argument by adding parts to the str Line 3487  each argument by adding parts to the str
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.
# Line 4392  function, in sequence.  These parts may Line 4344  function, in sequence.  These parts may
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
# Line 4522  Print a message in the echo area. The fi Line 4475  Print a message in the echo area. The fi
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
# Line 4631  then @key{RET}). Line 4584  then @key{RET}).
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    
# Line 4646  The @code{find-tags} function depends on Line 4599  The @code{find-tags} function depends on
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
# Line 4667  if it has already been created for you, Line 4620  if it has already been created for you,
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
# Line 4892  that the function will be used interacti Line 4845  that the function will be used interacti
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}
# Line 5476  command copies another buffer @emph{into Line 5430  command copies another buffer @emph{into
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.
# Line 5681  returns true, the @code{not} expression Line 5638  returns true, the @code{not} expression
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
# Line 5829  function sets a mark to this location. Line 5786  function sets a mark to this location.
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:
# Line 6143  position in the buffer. Line 6101  position in the buffer.
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
# Line 6157  Here is the complete text of the @code{b Line 6117  Here is the complete text of the @code{b
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."
# Line 6264  Return @code{t} if its argument is a buf Line 6226  Return @code{t} if its argument is a buf
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
# Line 6395  For example, Line 6358  For example,
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
# Line 6411  text of the function in full: Line 6374  text of the function in full:
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
# Line 6459  printed as a string of characters.  Howe Line 6432  printed as a string of characters.  Howe
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    
# Line 6484  the original narrowing, if any. Line 6458  the original narrowing, if any.
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
# Line 6570  daisy buttercup)} is @code{rose}, the re Line 6554  daisy buttercup)} is @code{rose}, the re
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
# Line 7080  The @code{setcdr} function is similar to Line 7064  The @code{setcdr} function is similar to
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:
# Line 7338  buffer only because of a mistake in the Line 7326  buffer only because of a mistake in the
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.
# Line 7559  contains the code that is called in the Line 7549  contains the code that is called in the
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
# Line 8140  the function copies the text into a sepa Line 8131  the function copies the text into a sepa
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)
# Line 8337  evaluated, it is bound to the value retu Line 8330  evaluated, it is bound to the value retu
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
# Line 8587  list---it takes the @sc{cdr} of the @sc{ Line 8580  list---it takes the @sc{cdr} of the @sc{
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
# Line 8717  commands.  However, before discussing th Line 8712  commands.  However, before discussing th
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
# Line 8842  search goes backwards. Line 8838  search goes backwards.
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
# Line 11522  using @code{cond}. Line 11518  using @code{cond}.
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    
# Line 14704  it uses the @code{<} function: Line 14713  it uses the @code{<} function:
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    
# Line 16096  and options; these are not featured in @ Line 16105  and options; these are not featured in @
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
# Line 16179  expression!  I do all time.  The purpose Line 16188  expression!  I do all time.  The purpose
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
# Line 16248  The first part of the file consists of c Line 16257  The first part of the file consists of c
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
# Line 16698  Reference Manual}, for more information Line 16708  Reference Manual}, for more information
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.
# Line 17080  Set the shape and color of the mouse cur Line 17086  Set the shape and color of the mouse cur
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
# Line 17159  has been modified, @code{mode-name} tell Line 17288  has been modified, @code{mode-name} tell
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    
# Line 17186  property name, in this case, @samp{help- Line 17316  property name, in this case, @samp{help-
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
# Line 17494  Debugger entered--beginning evaluation o Line 17623  Debugger entered--beginning evaluation o
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
# Line 17572  quickly until reaching a @dfn{breakpoint Line 17702  quickly until reaching a @dfn{breakpoint
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.
# Line 17659  Result: 3 = C-c Line 17790  Result: 3 = C-c
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:
# Line 17989  commands. Line 18121  commands.
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
# Line 18307  that the value of the whole expression Line 18440  that the value of the whole expression
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    
# Line 18383  evaluating Line 18517  evaluating
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    
# Line 18681  towards the beginning of the kill ring m Line 18816  towards the beginning of the kill ring m
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
# Line 18728  yank, point was left before the inserted Line 18863  yank, point was left before the inserted
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
# Line 18874  in the @code{let} for @code{print-graph} Line 19019  in the @code{let} for @code{print-graph}
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
# Line 18949  As usual in cases like this, a complex p Line 19095  As usual in cases like this, a complex p
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
# Line 19249  using the @code{Y-axis-element} function Line 19395  using the @code{Y-axis-element} function
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    
# Line 19324  Emacs will print labels vertically, the Line 19471  Emacs will print labels vertically, the
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
# Line 19666  Press @key{RET} to evaluate the expressi Line 19814  Press @key{RET} to evaluate the expressi
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
# Line 19920  Emacs will print a graph that looks like Line 20069  Emacs will print a graph that looks like
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    
# Line 20003  Evaluate the following: Line 20153  Evaluate the following:
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
# Line 20015  the @code{list-for-graph} has this value Line 20165  the @code{list-for-graph} has this value
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.
# Line 20063  Thus, Line 20213  Thus,
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
# Line 20991  each column." Line 21142  each column."
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
# Line 21031  Here is the graph: Line 21184  Here is the graph:
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
# Line 21052  of this license document, but changing i Line 21332  of this license document, but changing i
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
# Line 21075  principally for works whose purpose is i Line 21355  principally for works whose purpose is i
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
# Line 21134  formats which do not have any title page Line 21426  formats which do not have any title page
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    
# Line 21153  you may publicly display copies. Line 21460  you may publicly display copies.
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
# Line 21173  pages. Line 21481  pages.
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
# Line 21210  if the original publisher of that versio Line 21517  if the original publisher of that versio
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
# Line 21236  and required Cover Texts given in the Do Line 21544  and required Cover Texts given in the Do
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.
# Line 21254  least four years before the Document its Line 21562  least four years before the Document its
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,
# Line 21265  unaltered in their text and in their tit Line 21573  unaltered in their text and in their tit
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
# Line 21280  of these sections as invariant.  To do t Line 21591  of these sections as invariant.  To do t
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
# Line 21308  License, under the terms defined in sect Line 21619  License, under the terms defined in sect
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
# Line 21319  author or publisher of that section if k Line 21630  author or publisher of that section if k
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
# Line 21344  AGGREGATION WITH INDEPENDENT WORKS Line 21655  AGGREGATION WITH INDEPENDENT WORKS
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
# Line 21366  Replacing Invariant Sections with transl Line 21679  Replacing Invariant Sections with transl
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
# Line 21401  number of this License, you may choose a Line 21721  number of this License, you may choose a
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
# Line 21472  airplane. Line 21831  airplane.
21831  @end iftex  @end iftex
21832    
21833  @bye  @bye
21834    
21835    @ignore
21836       arch-tag: da1a2154-531f-43a8-8e33-fc7faad10acf
21837    @end ignore

Legend:
Removed from v.1.15.2.1  
changed lines
  Added in v.1.15.2.2

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26