--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/help.texi	Mon Aug 13 11:28:15 2007 +0200
@@ -0,0 +1,734 @@
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/help.info
+@node Documentation, Files, Modes, Top
+@chapter Documentation
+@cindex documentation strings
+
+  XEmacs Lisp has convenient on-line help facilities, most of which
+derive their information from the documentation strings associated with
+functions and variables.  This chapter describes how to write good
+documentation strings for your Lisp programs, as well as how to write
+programs to access documentation.
+
+  Note that the documentation strings for XEmacs are not the same thing
+as the XEmacs manual.  Manuals have their own source files, written in
+the Texinfo language; documentation strings are specified in the
+definitions of the functions and variables they apply to.  A collection
+of documentation strings is not sufficient as a manual because a good
+manual is not organized in that fashion; it is organized in terms of
+topics of discussion.
+
+@menu
+* Documentation Basics::      Good style for doc strings.
+                                Where to put them.  How XEmacs stores them.
+* Accessing Documentation::   How Lisp programs can access doc strings.
+* Keys in Documentation::     Substituting current key bindings.
+* Describing Characters::     Making printable descriptions of
+                                non-printing characters and key sequences.
+* Help Functions::            Subroutines used by XEmacs help facilities.
+* Obsoleteness::	      Upgrading Lisp functionality over time.
+@end menu
+
+@node Documentation Basics
+@section Documentation Basics
+@cindex documentation conventions
+@cindex writing a documentation string
+@cindex string, writing a doc string
+
+  A documentation string is written using the Lisp syntax for strings,
+with double-quote characters surrounding the text of the string.  This
+is because it really is a Lisp string object.  The string serves as
+documentation when it is written in the proper place in the definition
+of a function or variable.  In a function definition, the documentation
+string follows the argument list.  In a variable definition, the
+documentation string follows the initial value of the variable.
+
+  When you write a documentation string, make the first line a complete
+sentence (or two complete sentences) since some commands, such as
+@code{apropos}, show only the first line of a multi-line documentation
+string.  Also, you should not indent the second line of a documentation
+string, if you have one, because that looks odd when you use @kbd{C-h f}
+(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}).
+@xref{Documentation Tips}.
+
+  Documentation strings may contain several special substrings, which
+stand for key bindings to be looked up in the current keymaps when the
+documentation is displayed.  This allows documentation strings to refer
+to the keys for related commands and be accurate even when a user
+rearranges the key bindings.  (@xref{Accessing Documentation}.)
+
+  Within the Lisp world, a documentation string is accessible through
+the function or variable that it describes:
+
+@itemize @bullet
+@item
+The documentation for a function is stored in the function definition
+itself (@pxref{Lambda Expressions}).  The function
+@code{documentation} knows how to extract it.
+
+@item
+@kindex variable-documentation
+The documentation for a variable is stored in the variable's property
+list under the property name @code{variable-documentation}.  The
+function @code{documentation-property} knows how to extract it.
+@end itemize
+
+@cindex @file{DOC} (documentation) file
+To save space, the documentation for preloaded functions and variables
+(including primitive functions and autoloaded functions) is stored in
+the @dfn{internal doc file} @file{DOC}.  The documentation for functions
+and variables loaded during the XEmacs session from byte-compiled files
+is stored in those very same byte-compiled files (@pxref{Docs and
+Compilation}).
+
+XEmacs does not keep documentation strings in memory unless necessary.
+Instead, XEmacs maintains, for preloaded symbols, an integer offset into
+the internal doc file, and for symbols loaded from byte-compiled files,
+a list containing the filename of the byte-compiled file and an integer
+offset, in place of the documentation string.  The functions
+@code{documentation} and @code{documentation-property} use that
+information to read the documentation from the appropriate file; this is
+transparent to the user.
+
+  For information on the uses of documentation strings, see @ref{Help, ,
+Help, emacs, The XEmacs Reference Manual}.
+
+@c Wordy to prevent overfull hbox.  --rjc 15mar92
+  The @file{emacs/lib-src} directory contains two utilities that you can
+use to print nice-looking hardcopy for the file
+@file{emacs/etc/DOC-@var{version}}.  These are @file{sorted-doc.c} and
+@file{digest-doc.c}.
+
+@node Accessing Documentation
+@section Access to Documentation Strings
+
+@defun documentation-property symbol property &optional verbatim
+This function returns the documentation string that is recorded in
+@var{symbol}'s property list under property @var{property}.  It
+retrieves the text from a file if necessary, and runs
+@code{substitute-command-keys} to substitute actual key bindings.  (This
+substitution is not done if @var{verbatim} is non-@code{nil}; the
+@var{verbatim} argument exists only as of Emacs 19.)
+
+@smallexample
+@group
+(documentation-property 'command-line-processed
+   'variable-documentation)
+     @result{} "t once command line has been processed"
+@end group
+@group
+(symbol-plist 'command-line-processed)
+     @result{} (variable-documentation 188902)
+@end group
+@end smallexample
+@end defun
+
+@defun documentation function &optional verbatim
+This function returns the documentation string of @var{function}.  It
+reads the text from a file if necessary.  Then (unless @var{verbatim} is
+non-@code{nil}) it calls @code{substitute-command-keys}, to return a
+value containing the actual (current) key bindings.
+
+The function @code{documentation} signals a @code{void-function} error
+if @var{function} has no function definition.  However, it is ok if
+the function definition has no documentation string.  In that case,
+@code{documentation} returns @code{nil}.
+@end defun
+
+@c Wordy to prevent overfull hboxes.  --rjc 15mar92
+Here is an example of using the two functions, @code{documentation} and
+@code{documentation-property}, to display the documentation strings for
+several symbols in a @samp{*Help*} buffer.
+
+@smallexample
+@group
+(defun describe-symbols (pattern)
+  "Describe the XEmacs Lisp symbols matching PATTERN.
+All symbols that have PATTERN in their name are described
+in the `*Help*' buffer."
+  (interactive "sDescribe symbols matching: ")
+  (let ((describe-func
+         (function
+          (lambda (s)
+@end group
+@group
+            ;; @r{Print description of symbol.}
+            (if (fboundp s)             ; @r{It is a function.}
+                (princ
+                 (format "%s\t%s\n%s\n\n" s
+                   (if (commandp s)
+                       (let ((keys (where-is-internal s)))
+                         (if keys
+                             (concat
+                              "Keys: "
+                              (mapconcat 'key-description
+                                         keys " "))
+                           "Keys: none"))
+                     "Function")
+@end group
+@group
+                   (or (documentation s)
+                       "not documented"))))
+
+            (if (boundp s)              ; @r{It is a variable.}
+@end group
+@group
+                (princ
+                 (format "%s\t%s\n%s\n\n" s
+                   (if (user-variable-p s)
+                       "Option " "Variable")
+@end group
+@group
+                   (or (documentation-property
+                         s 'variable-documentation)
+                       "not documented")))))))
+        sym-list)
+@end group
+
+@group
+    ;; @r{Build a list of symbols that match pattern.}
+    (mapatoms (function
+               (lambda (sym)
+                 (if (string-match pattern (symbol-name sym))
+                     (setq sym-list (cons sym sym-list))))))
+@end group
+
+@group
+    ;; @r{Display the data.}
+    (with-output-to-temp-buffer "*Help*"
+      (mapcar describe-func (sort sym-list 'string<))
+      (print-help-return-message))))
+@end group
+@end smallexample
+
+  The @code{describe-symbols} function works like @code{apropos},
+but provides more information.
+
+@smallexample
+@group
+(describe-symbols "goal")
+
+---------- Buffer: *Help* ----------
+goal-column     Option
+*Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
+@end group
+@c Do not blithely break or fill these lines.
+@c That makes them incorrect.
+
+@group
+set-goal-column Command: C-x C-n
+Set the current horizontal position as a goal for C-n and C-p.
+@end group
+@c DO NOT put a blank line here!  That is factually inaccurate!
+@group
+Those commands will move to this position in the line moved to
+rather than trying to keep the same horizontal position.
+With a non-nil argument, clears out the goal column
+so that C-n and C-p resume vertical motion.
+The goal column is stored in the variable `goal-column'.
+@end group
+
+@group
+temporary-goal-column   Variable
+Current goal column for vertical motion.
+It is the column where point was
+at the start of current run of vertical motion commands.
+When the `track-eol' feature is doing its job, the value is 9999.
+---------- Buffer: *Help* ----------
+@end group
+@end smallexample
+
+@defun Snarf-documentation filename
+  This function is used only during XEmacs initialization, just before
+the runnable XEmacs is dumped.  It finds the file offsets of the
+documentation strings stored in the file @var{filename}, and records
+them in the in-core function definitions and variable property lists in
+place of the actual strings.  @xref{Building XEmacs}.
+
+  XEmacs finds the file @var{filename} in the @file{lib-src} directory.
+When the dumped XEmacs is later executed, the same file is found in the
+directory @code{doc-directory}.  The usual value for @var{filename} is
+@file{DOC}, but this can be changed by modifying the variable
+@code{internal-doc-file-name}.
+@end defun
+
+@defvar internal-doc-file-name
+This variable holds the name of the file containing documentation
+strings of built-in symbols, usually @file{DOC}.  The full pathname of
+the internal doc file is @samp{(concat doc-directory internal-doc-file-name)}.
+@end defvar
+
+@defvar doc-directory
+This variable holds the name of the directory which contains the
+@dfn{internal doc file} that contains documentation strings for built-in
+and preloaded functions and variables.
+
+In most cases, this is the same as @code{exec-directory}.  They may be
+different when you run XEmacs from the directory where you built it,
+without actually installing it.  See @code{exec-directory} in @ref{Help
+Functions}.
+
+In older Emacs versions, @code{exec-directory} was used for this.
+@end defvar
+
+@defvar data-directory
+This variable holds the name of the directory in which XEmacs finds
+certain system independent documentation and text files that come
+with XEmacs.  In older Emacs versions, @code{exec-directory} was used for
+this.
+@end defvar
+
+@node Keys in Documentation
+@section Substituting Key Bindings in Documentation
+@cindex documentation, keys in
+@cindex keys in documentation strings
+@cindex substituting keys in documentation
+
+  When documentation strings refer to key sequences, they should use the
+current, actual key bindings.  They can do so using certain special text
+sequences described below.  Accessing documentation strings in the usual
+way substitutes current key binding information for these special
+sequences.  This works by calling @code{substitute-command-keys}.  You
+can also call that function yourself.
+
+  Here is a list of the special sequences and what they mean:
+
+@table @code
+@item \[@var{command}]
+stands for a key sequence that will invoke @var{command}, or @samp{M-x
+@var{command}} if @var{command} has no key bindings.
+
+@item \@{@var{mapvar}@}
+stands for a summary of the value of @var{mapvar}, which should be a
+keymap.  The summary is made by @code{describe-bindings}.
+
+@item \<@var{mapvar}>
+stands for no text itself.  It is used for a side effect: it specifies
+@var{mapvar} as the keymap for any following @samp{\[@var{command}]}
+sequences in this documentation string.
+
+@item \=
+quotes the following character and is discarded; this @samp{\=\=} puts
+@samp{\=} into the output, and @samp{\=\[} puts @samp{\[} into the output.
+@end table
+
+@strong{Please note:} Each @samp{\} must be doubled when written in a
+string in XEmacs Lisp.
+
+@defun substitute-command-keys string
+This function scans @var{string} for the above special sequences and
+replaces them by what they stand for, returning the result as a string.
+This permits display of documentation that refers accurately to the
+user's own customized key bindings.
+@end defun
+
+  Here are examples of the special sequences:
+
+@smallexample
+@group
+(substitute-command-keys
+   "To abort recursive edit, type: \\[abort-recursive-edit]")
+@result{} "To abort recursive edit, type: C-]"
+@end group
+
+@group
+(substitute-command-keys
+   "The keys that are defined for the minibuffer here are:
+  \\@{minibuffer-local-must-match-map@}")
+@result{} "The keys that are defined for the minibuffer here are:
+@end group
+
+?               minibuffer-completion-help
+SPC             minibuffer-complete-word
+TAB             minibuffer-complete
+LFD             minibuffer-complete-and-exit
+RET             minibuffer-complete-and-exit
+C-g             abort-recursive-edit
+"
+
+@group
+(substitute-command-keys
+   "To abort a recursive edit from the minibuffer, type\
+\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
+@result{} "To abort a recursive edit from the minibuffer, type C-g."
+@end group
+
+@group
+(substitute-command-keys
+  "Substrings of the form \\=\\@{MAPVAR@} are replaced by summaries
+\(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
+Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
+as the keymap for future \\=\\[COMMAND] substrings.
+\\=\\= quotes the following character and is discarded;
+thus, \\=\\=\\=\\= puts \\=\\= into the output,
+and \\=\\=\\=\\[ puts \\=\\[ into the output.")
+@result{} "Substrings of the form \@{MAPVAR@} are replaced by summaries
+(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
+Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
+as the keymap for future \[COMMAND] substrings.
+\= quotes the following character and is discarded;
+thus, \=\= puts \= into the output,
+and \=\[ puts \[ into the output."
+@end group
+@end smallexample
+
+@node Describing Characters
+@section Describing Characters for Help Messages
+
+  These functions convert events, key sequences or characters to textual
+descriptions.  These descriptions are useful for including arbitrary
+text characters or key sequences in messages, because they convert
+non-printing and whitespace characters to sequences of printing
+characters.  The description of a non-whitespace printing character is
+the character itself.
+
+@defun key-description sequence
+@cindex XEmacs event standard notation
+This function returns a string containing the XEmacs standard notation
+for the input events in @var{sequence}.  The argument @var{sequence} may
+be a string, vector or list.  @xref{Events}, for more information about
+valid events.  See also the examples for @code{single-key-description},
+below.
+@end defun
+
+@defun single-key-description key
+@cindex event printing
+@cindex character printing
+@cindex control character printing
+@cindex meta character printing
+This function returns a string describing @var{key} in the standard
+XEmacs notation for keyboard input.  A normal printing character appears
+as itself, but a control character turns into a string starting with
+@samp{C-}, a meta character turns into a string starting with @samp{M-},
+and space, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc.  A
+symbol appears as the name of the symbol.  An event that is a list
+appears as the name of the symbol in the @sc{car} of the list.
+
+@smallexample
+@group
+(single-key-description ?\C-x)
+     @result{} "C-x"
+@end group
+@group
+(key-description "\C-x \M-y \n \t \r \f123")
+     @result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
+@end group
+@group
+(single-key-description 'kp_next)
+     @result{} "kp_next"
+@end group
+@group
+(single-key-description '(shift button1))
+     @result{} "Sh-button1"
+@end group
+@end smallexample
+@end defun
+
+@defun text-char-description character
+This function returns a string describing @var{character} in the
+standard XEmacs notation for characters that appear in text---like
+@code{single-key-description}, except that control characters are
+represented with a leading caret (which is how control characters in
+XEmacs buffers are usually displayed).
+
+@smallexample
+@group
+(text-char-description ?\C-c)
+     @result{} "^C"
+@end group
+@group
+(text-char-description ?\M-m)
+     @result{} "M-m"
+@end group
+@group
+(text-char-description ?\C-\M-m)
+     @result{} "M-^M"
+@end group
+@end smallexample
+@end defun
+
+@node Help Functions
+@section Help Functions
+
+  XEmacs provides a variety of on-line help functions, all accessible to
+the user as subcommands of the prefix @kbd{C-h}, or on some keyboards,
+@kbd{help}.  For more information about them, see @ref{Help, , Help,
+emacs, The XEmacs Reference Manual}.  Here we describe some
+program-level interfaces to the same information.
+
+@deffn Command apropos regexp &optional do-all predicate
+This function finds all symbols whose names contain a match for the
+regular expression @var{regexp}, and returns a list of them
+(@pxref{Regular Expressions}).  It also displays the symbols in a buffer
+named @samp{*Help*}, each with a one-line description.
+
+@c Emacs 19 feature
+If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
+key bindings for the functions that are found.
+
+If @var{predicate} is non-@code{nil}, it should be a function to be
+called on each symbol that has matched @var{regexp}.  Only symbols for
+which @var{predicate} returns a non-@code{nil} value are listed or
+displayed.
+
+In the first of the following examples, @code{apropos} finds all the
+symbols with names containing @samp{exec}.  In the second example, it
+finds and returns only those symbols that are also commands.
+(We don't show the output that results in the @samp{*Help*} buffer.)
+
+@smallexample
+@group
+(apropos "exec")
+     @result{} (Buffer-menu-execute command-execute exec-directory
+    exec-path execute-extended-command execute-kbd-macro
+    executing-kbd-macro executing-macro)
+@end group
+
+@group
+(apropos "exec" nil 'commandp)
+     @result{} (Buffer-menu-execute execute-extended-command)
+@end group
+@ignore
+@group
+---------- Buffer: *Help* ----------
+Buffer-menu-execute
+  Function: Save and/or delete buffers marked with
+  M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
+execute-extended-command      ESC x
+  Function: Read function name, then read its
+  arguments and call it.
+---------- Buffer: *Help* ----------
+@end group
+@end ignore
+@end smallexample
+
+@code{apropos} is used by various user-level commands, such as @kbd{C-h
+a} (@code{hyper-apropos}), a graphical front-end to @code{apropos}; and
+@kbd{C-h A} (@code{command-apropos}), which does an apropos over only
+those functions which are user commands.  @code{command-apropos} calls
+@code{apropos}, specifying a @var{predicate} to restrict the output to
+symbols that are commands.  The call to @code{apropos} looks like this:
+
+@smallexample
+(apropos string t 'commandp)
+@end smallexample
+@end deffn
+
+@c Emacs 19 feature
+@c super-apropos is obsolete - function absorbed by apropos --mrb
+@ignore
+@deffn Command super-apropos regexp &optional do-all
+This function differs from @code{apropos} in that it searches
+documentation strings as well as symbol names for matches for
+@var{regexp}.  By default, it searches the documentation strings only
+for preloaded functions and variables.  If @var{do-all} is
+non-@code{nil}, it scans the names and documentation strings of all
+functions and variables.
+@end deffn
+@end ignore
+
+@defvar help-map
+The value of this variable is a local keymap for characters following the
+Help key, @kbd{C-h}.
+@end defvar
+
+@deffn {Prefix Command} help-command
+This symbol is not a function; its function definition is actually the
+keymap known as @code{help-map}.  It is defined in @file{help.el} as
+follows:
+
+@smallexample
+@group
+(define-key global-map "\C-h" 'help-command)
+(fset 'help-command help-map)
+@end group
+@end smallexample
+@end deffn
+
+@defun print-help-return-message &optional function
+This function builds a string that explains how to restore the previous
+state of the windows after a help command.  After building the message,
+it applies @var{function} to it if @var{function} is non-@code{nil}.
+Otherwise it calls @code{message} to display it in the echo area.
+
+This function expects to be called inside a
+@code{with-output-to-temp-buffer} special form, and expects
+@code{standard-output} to have the value bound by that special form.
+For an example of its use, see the long example in @ref{Accessing
+Documentation}.
+@end defun
+
+@defvar help-char
+The value of this variable is the help character---the character that
+XEmacs recognizes as meaning Help.  By default, it is the character
+@samp{?\^H} (ASCII 8), which is @kbd{C-h}.  When XEmacs reads this
+character, if @code{help-form} is non-@code{nil} Lisp expression, it
+evaluates that expression, and displays the result in a window if it is
+a string.
+
+@code{help-char} can be a character or a key description such as
+@code{help} or @code{(meta h)}.
+
+Usually the value of @code{help-form}'s value is @code{nil}.  Then the
+help character has no special meaning at the level of command input, and
+it becomes part of a key sequence in the normal way.  The standard key
+binding of @kbd{C-h} is a prefix key for several general-purpose help
+features.
+
+The help character is special after prefix keys, too.  If it has no
+binding as a subcommand of the prefix key, it runs
+@code{describe-prefix-bindings}, which displays a list of all the
+subcommands of the prefix key.
+@end defvar
+
+@defvar help-form
+If this variable is non-@code{nil}, its value is a form to evaluate
+whenever the character @code{help-char} is read.  If evaluating the form
+produces a string, that string is displayed.
+
+A command that calls @code{next-command-event} or @code{next-event}
+probably should bind @code{help-form} to a non-@code{nil} expression
+while it does input.  (The exception is when @kbd{C-h} is meaningful
+input.)  Evaluating this expression should result in a string that
+explains what the input is for and how to enter it properly.
+
+Entry to the minibuffer binds this variable to the value of
+@code{minibuffer-help-form} (@pxref{Minibuffer Misc}).
+@end defvar
+
+@defvar prefix-help-command
+This variable holds a function to print help for a prefix character.
+The function is called when the user types a prefix key followed by the
+help character, and the help character has no binding after that prefix.
+The variable's default value is @code{describe-prefix-bindings}.
+@end defvar
+
+@defun describe-prefix-bindings
+This function calls @code{describe-bindings} to display a list of all
+the subcommands of the prefix key of the most recent key sequence.  The
+prefix described consists of all but the last event of that key
+sequence.  (The last event is, presumably, the help character.)
+@end defun
+
+  The following two functions are found in the library @file{helper}.
+They are for modes that want to provide help without relinquishing
+control, such as the ``electric'' modes.  You must load that library
+with @code{(require 'helper)} in order to use them.  Their names begin
+with @samp{Helper} to distinguish them from the ordinary help functions.
+
+@deffn Command Helper-describe-bindings
+This command pops up a window displaying a help buffer containing a
+listing of all of the key bindings from both the local and global keymaps.
+It works by calling @code{describe-bindings}.
+@end deffn
+
+@deffn Command Helper-help
+This command provides help for the current mode.  It prompts the user
+in the minibuffer with the message @samp{Help (Type ? for further
+options)}, and then provides assistance in finding out what the key
+bindings are, and what the mode is intended for.  It returns @code{nil}.
+
+This can be customized by changing the map @code{Helper-help-map}.
+@end deffn
+
+@ignore @c Not in XEmacs currently
+@c Emacs 19 feature
+@defmac make-help-screen fname help-line help-text help-map
+This macro defines a help command named @var{fname} that acts like a
+prefix key that shows a list of the subcommands it offers.
+
+When invoked, @var{fname} displays @var{help-text} in a window, then
+reads and executes a key sequence according to @var{help-map}.  The
+string @var{help-text} should describe the bindings available in
+@var{help-map}.
+
+The command @var{fname} is defined to handle a few events itself, by
+scrolling the display of @var{help-text}.  When @var{fname} reads one of
+those special events, it does the scrolling and then reads another
+event.  When it reads an event that is not one of those few, and which
+has a binding in @var{help-map}, it executes that key's binding and
+then returns.
+
+The argument @var{help-line} should be a single-line summary of the
+alternatives in @var{help-map}.  In the current version of Emacs, this
+argument is used only if you set the option @code{three-step-help} to
+@code{t}.
+@end defmac
+
+@defopt three-step-help
+If this variable is non-@code{nil}, commands defined with
+@code{make-help-screen} display their @var{help-line} strings in the
+echo area at first, and display the longer @var{help-text} strings only
+if the user types the help character again.
+@end defopt
+@end ignore
+
+@node Obsoleteness
+@section Obsoleteness
+
+As you add functionality to a package, you may at times want to
+replace an older function with a new one.  To preserve compatibility
+with existing code, the older function needs to still exist; but
+users of that function should be told to use the newer one instead.
+XEmacs Lisp lets you mark a function or variable as @dfn{obsolete},
+and indicate what should be used instead.
+
+@defun make-obsolete function new
+This function indicates that @var{function} is an obsolete function,
+and the function @var{new} should be used instead.  The byte compiler
+will issue a warning to this effect when it encounters a usage of the
+older function, and the help system will also note this in the function's
+documentation.  @var{new} can also be a string (if there is not a single
+function with the same functionality any more), and should be a descriptive
+statement, such as "use @var{foo} or @var{bar} instead" or "this function is
+unnecessary".
+@end defun
+
+@defun make-obsolete-variable variable new
+This is like @code{make-obsolete} but is for variables instead of functions.
+@end defun
+
+@defun define-obsolete-function-alias oldfun newfun
+This function combines @code{make-obsolete} and @code{define-function},
+declaring @var{oldfun} to be an obsolete variant of @var{newfun} and
+defining @var{oldfun} as an alias for @var{newfun}.
+@end defun
+
+@defun define-obsolete-variable-alias oldvar newvar
+This is like @code{define-obsolete-function-alias} but for variables.
+@end defun
+
+Note that you should not normally put obsoleteness information
+explicitly in a function or variable's doc string.  The obsoleteness
+information that you specify using the above functions will be displayed
+whenever the doc string is displayed, and by adding it explicitly the
+result is redundancy.
+
+Also, if an obsolete function is substantially the same as a newer one
+but is not actually an alias, you should consider omitting the doc
+string entirely (use a null string @samp{""} as the doc string).  That
+way, the user is told about the obsoleteness and is forced to look at
+the documentation of the new function, making it more likely that he
+will use the new function.
+
+@defun function-obsoleteness-doc function
+If @var{function} is obsolete, this function returns a string describing
+this.  This is the message that is printed out during byte compilation
+or in the function's documentation.  If @var{function} is not obsolete,
+@code{nil} is returned.
+@end defun
+
+@defun variable-obsoleteness-doc variable
+This is like @code{function-obsoleteness-doc} but for variables.
+@end defun
+
+The obsoleteness information is stored internally by putting a property
+@code{byte-obsolete-info} (for functions) or
+@code{byte-obsolete-variable} (for variables) on the symbol that
+specifies the obsolete function or variable.  For more information, see
+the implementation of @code{make-obsolete} and
+@code{make-obsolete-variable} in
+@file{lisp/bytecomp/bytecomp-runtime.el}.