-@need 1500
-Like many of the other Emacs primitives,
-@code{delete-and-extract-region} is written as an instance of a C
-macro, a macro being a template for code. The complete macro looks
-like this:
-
-@c /usr/local/src/emacs/src/editfns.c
-@smallexample
-@group
-DEFUN ("delete-and-extract-region", Fdelete_and_extract_region,
- Sdelete_and_extract_region, 2, 2, 0,
- "Delete the text between START and END and return it.")
- (start, end)
- Lisp_Object start, end;
-@{
- validate_region (&start, &end);
- return del_range_1 (XINT (start), XINT (end), 1, 1);
-@}
-@end group
-@end smallexample
-
-Without going into the details of the macro writing process, let me
-point out that this macro starts with the word @code{DEFUN}. The word
-@code{DEFUN} was chosen since the code serves the same purpose as
-@code{defun} does in Lisp. The word @code{DEFUN} is followed by seven
-parts inside of parentheses:
-
-@itemize @bullet
-@item
-The first part is the name given to the function in Lisp,
-@code{delete-and-extract-region}.
-
-@item
-The second part is the name of the function in C,
-@code{Fdelete_and_extract_region}. By convention, it starts with
-@samp{F}. Since C does not use hyphens in names, underscores are used
-instead.
-
-@item
-The third part is the name for the C constant structure that records
-information on this function for internal use. It is the name of the
-function in C but begins with an @samp{S} instead of an @samp{F}.
-
-@item
-The fourth and fifth parts specify the minimum and maximum number of
-arguments the function can have. This function demands exactly 2
-arguments.
-
-@item
-The sixth part is nearly like the argument that follows the
-@code{interactive} declaration in a function written in Lisp: a letter
-followed, perhaps, by a prompt. The only difference from the Lisp is
-when the macro is called with no arguments. Then you write a @code{0}
-(which is a `null string'), as in this macro.
-
-If you were to specify arguments, you would place them between
-quotation marks. The C macro for @code{goto-char} includes
-@code{"NGoto char: "} in this position to indicate that the function
-expects a raw prefix, in this case, a numerical location in a buffer,
-and provides a prompt.
-
-@item
-The seventh part is a documentation string, just like the one for a
-function written in Emacs Lisp, except that every newline must be
-written explicitly as @samp{\n} followed by a backslash and carriage
-return.
-
-@need 1000
-Thus, the first two lines of documentation for @code{goto-char} are
-written like this:
-
-@smallexample
-@group
- "Set point to POSITION, a number or marker.\n\
-Beginning of buffer is position (point-min), end is (point-max).
-@end group
-@end smallexample
-@end itemize
-
-@need 1200
-In a C macro, the formal parameters come next, with a statement of
-what kind of object they are, followed by what might be called the `body'
-of the macro. For @code{delete-and-extract-region} the `body'
-consists of the following two lines:
-
-@smallexample
-@group
-validate_region (&start, &end);
-return del_range_1 (XINT (start), XINT (end), 1, 1);
-@end group
-@end smallexample
-
-The first function, @code{validate_region} checks whether the values
-passed as the beginning and end of the region are the proper type and
-are within range. The second function, @code{del_range_1}, actually
-deletes the text.
-
-@code{del_range_1} is a complex function we will not look into. It
-updates the buffer and does other things.
-
-However, it is worth looking at the two arguments passed to
-@code{del_range}. These are @w{@code{XINT (start)}} and @w{@code{XINT
-(end)}}.
-
-As far as the C language is concerned, @code{start} and @code{end} are
-two integers that mark the beginning and end of the region to be
-deleted@footnote{More precisely, and requiring more expert knowledge
-to understand, the two integers are of type `Lisp_Object', which can
-also be a C union instead of an integer type.}.
-
-In early versions of Emacs, these two numbers were thirty-two bits
-long, but the code is slowly being generalized to handle other
-lengths. Three of the available bits are used to specify the type of
-information and a fourth bit is used for handling the computer's
-memory; the remaining bits are used as `content'.
-
-@samp{XINT} is a C macro that extracts the relevant number from the
-longer collection of bits; the four other bits are discarded.
-
-@need 800
-The command in @code{delete-and-extract-region} looks like this:
-
-@smallexample
-del_range_1 (XINT (start), XINT (end), 1, 1);
-@end smallexample
-
-@noindent
-It deletes the region between the beginning position, @code{start},
-and the ending position, @code{end}.
-
-From the point of view of the person writing Lisp, Emacs is all very
-simple; but hidden underneath is a great deal of complexity to make it
-all work.
-
-@node defvar, copy-region-as-kill, Digression into C, Cutting & Storing Text
-@comment node-name, next, previous, up
-@section Initializing a Variable with @code{defvar}
-@findex defvar
-@cindex Initializing a variable
-@cindex Variable initialization
-
-Unlike the @code{delete-and-extract-region} function, the
-@code{copy-region-as-kill} function is written in Emacs Lisp. Two
-functions within it, @code{kill-append} and @code{kill-new}, copy a
-region in a buffer and save it in a variable called the
-@code{kill-ring}. This section describes how the @code{kill-ring}
-variable is created and initialized using the @code{defvar} special
-form.
-
-(Again we note that the term @code{kill-ring} is a misnomer. The text
-that is clipped out of the buffer can be brought back; it is not a ring
-of corpses, but a ring of resurrectable text.)
-
-In Emacs Lisp, a variable such as the @code{kill-ring} is created and
-given an initial value by using the @code{defvar} special form. The
-name comes from ``define variable''.
-
-The @code{defvar} special form is similar to @code{setq} in that it sets
-the value of a variable. It is unlike @code{setq} in two ways: first,
-it only sets the value of the variable if the variable does not already
-have a value. If the variable already has a value, @code{defvar} does
-not override the existing value. Second, @code{defvar} has a
-documentation string.
-
-(Another special form, @code{defcustom}, is designed for variables
-that people customize. It has more features than @code{defvar}.
-(@xref{defcustom, , Setting Variables with @code{defcustom}}.)
-
-@menu
-* See variable current value::
-* defvar and asterisk:: An old-time convention.
-@end menu
-
-@node See variable current value, defvar and asterisk, defvar, defvar
-@ifnottex
-@unnumberedsubsec Seeing the Current Value of a Variable
-@end ifnottex
-
-You can see the current value of a variable, any variable, by using
-the @code{describe-variable} function, which is usually invoked by
-typing @kbd{C-h v}. If you type @kbd{C-h v} and then @code{kill-ring}
-(followed by @key{RET}) when prompted, you will see what is in your
-current kill ring---this may be quite a lot! Conversely, if you have
-been doing nothing this Emacs session except read this document, you
-may have nothing in it. Also, you will see the documentation for
-@code{kill-ring}:
-
-@smallexample
-@group
-Documentation:
-List of killed text sequences.
-Since the kill ring is supposed to interact nicely with cut-and-paste
-facilities offered by window systems, use of this variable should
-@end group
-@group
-interact nicely with `interprogram-cut-function' and
-`interprogram-paste-function'. The functions `kill-new',
-`kill-append', and `current-kill' are supposed to implement this
-interaction; you may want to use them instead of manipulating the kill
-ring directly.
-@end group
-@end smallexample
-
-@need 800
-The kill ring is defined by a @code{defvar} in the following way:
-
-@smallexample
-@group
-(defvar kill-ring nil
- "List of killed text sequences.
-@dots{}")
-@end group
-@end smallexample
-
-@noindent
-In this variable definition, the variable is given an initial value of
-@code{nil}, which makes sense, since if you have saved nothing, you want
-nothing back if you give a @code{yank} command. The documentation
-string is written just like the documentation string of a @code{defun}.
-As with the documentation string of the @code{defun}, the first line of
-the documentation should be a complete sentence, since some commands,
-like @code{apropos}, print only the first line of documentation.
-Succeeding lines should not be indented; otherwise they look odd when
-you use @kbd{C-h v} (@code{describe-variable}).
-
-@node defvar and asterisk, , See variable current value, defvar
-@subsection @code{defvar} and an asterisk
-@findex defvar @r{for a user customizable variable}
-@findex defvar @r{with an asterisk}
-
-In the past, Emacs used the @code{defvar} special form both for
-internal variables that you would not expect a user to change and for
-variables that you do expect a user to change. Although you can still
-use @code{defvar} for user customizable variables, please use
-@code{defcustom} instead, since that special form provides a path into
-the Customization commands. (@xref{defcustom, , Setting Variables
-with @code{defcustom}}.)
-
-When you specified a variable using the @code{defvar} special form,
-you could distinguish a readily settable variable from others by
-typing an asterisk, @samp{*}, in the first column of its documentation
-string. For example:
-
-@smallexample
-@group
-(defvar shell-command-default-error-buffer nil
- "*Buffer name for `shell-command' @dots{} error output.
-@dots{} ")
-@end group
-@end smallexample
-
-@noindent
-This means that you could (and still can) use the @code{edit-options}
-command to change the value of
-@code{shell-command-default-error-buffer} temporarily.
-
-@findex edit-options
-However, options set using @code{edit-options} are set only for the
-duration of your editing session. The new values are not saved
-between sessions. Each time Emacs starts, it reads the original
-value, unless you change the value within your @file{.emacs} file,
-either by setting it manually or by using @code{customize}.
-@xref{Emacs Initialization, , Your @file{.emacs} File}.
-
-For me, the major use of the @code{edit-options} command is to suggest
-variables that I might want to set in my @file{.emacs} file. I urge
-you to look through the list. (@xref{Edit Options, , Editing Variable
-Values, emacs, The GNU Emacs Manual}.)
-
-@node copy-region-as-kill, cons & search-fwd Review, defvar, Cutting & Storing Text
-@comment node-name, next, previous, up
-@section @code{copy-region-as-kill}
-@findex copy-region-as-kill
-@findex nthcdr
-
-The @code{copy-region-as-kill} function copies a region of text from a
-buffer and (via either @code{kill-append} or @code{kill-new}) saves it
-in the @code{kill-ring}.
-
-If you call @code{copy-region-as-kill} immediately after a
-@code{kill-region} command, Emacs appends the newly copied text to the
-previously copied text. This means that if you yank back the text, you
-get it all, from both this and the previous operation. On the other
-hand, if some other command precedes the @code{copy-region-as-kill},
-the function copies the text into a separate entry in the kill ring.
-
-@menu
-* Complete copy-region-as-kill:: The complete function definition.
-* copy-region-as-kill body:: The body of @code{copy-region-as-kill}.
-@end menu
-
-@node Complete copy-region-as-kill, copy-region-as-kill body, copy-region-as-kill, copy-region-as-kill
-@ifnottex
-@unnumberedsubsec The complete @code{copy-region-as-kill} function definition
-@end ifnottex
-
-@need 1200
-Here is the complete text of the version 21 @code{copy-region-as-kill}
-function: