Mercurial > emacs

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lispref/help.texi	Wed Mar 16 19:53:19 1994 +0000
@@ -0,0 +1,624 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/help
+@node Documentation, Files, Modes, Top
+@chapter Documentation
+@cindex documentation strings
+
+  GNU Emacs 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 Emacs are not the same thing
+as the Emacs 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 Emacs 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 Emacs help facilities.
+@end menu
+
+@node Documentation Basics
+@comment  node-name,  next,  previous,  up
+@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 kept with 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
+@cindex @file{emacs/etc/DOC-@var{version}}
+@cindex @file{etc/DOC-@var{version}}
+To save space, the documentation for preloaded functions and variables
+(including primitive functions and autoloaded functions) are stored in
+the file @file{emacs/etc/DOC-@var{version}}.  The data structure inside
+Emacs has an integer offset into the file, where the documentation
+string ought to be.  The functions @code{documentation} the
+@code{documentation-property} read the documentation from the file
+@file{emacs/etc/DOC-@var{version}} when they notice the integer there;
+this is transparent to the user.  Keeping the documentation strings out
+of the Emacs core image saves a significant amount of space.
+@xref{Building Emacs}.
+
+  For information on the uses of documentation strings, see @ref{Help, ,
+Help, emacs, The GNU Emacs Manual}.
+
+@c Wordy to prevent overfull hbox.  --rjc 15mar92
+  The @file{emacs/etc} 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
+@var{symbol}'s property list under property @var{property}.  It
+retrieves the text from the file @file{emacs/etc/DOC-@var{version}} 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}.
+This function will access the documentation string if it is stored in
+the @file{emacs/etc/DOC-@var{version}} file.
+
+In addition, @code{documentation} runs @code{substitute-command-keys}
+on the resulting string, so the value contains the actual (current) key
+bindings.  (This is not done if @var{verbatim} is non-@code{nil}; the
+@var{verbatim} argument exists only as of Emacs 19.)
+
+The function @code{documentation} signals a @code{void-function} error
+unless @var{function} has a 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 Emacs 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 Emacs initialization, just before
+the runnable Emacs 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 Emacs}.
+
+  Emacs finds the file @var{filename} in the @file{emacs/etc} directory.
+When the dumped Emacs is later executed, the same file is found in the
+directory @code{doc-directory}.  Usually @var{filename} is
+@code{"DOC-@var{version}"}.
+@end defun
+
+@c Emacs 19 feature
+@defvar doc-directory
+This variable holds the name of the directory which should contion the
+file @code{"DOC-@var{version}"} that contains documentation strings for
+built-in and preloaded functions and variables.
+
+In most cases, this is the same as @code{data-directory}.  They may be
+different when you run Emacs from the directory where you built it,
+without actually installing it.  See @code{data-directory} in @ref{Help
+Functions}.
+
+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 do so
+based on 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.
+@end table
+
+@strong{Please note:} each @samp{\} must be doubled when written in a
+string in Emacs 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
+users'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
+@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 Emacs event standard notation
+This function returns a string containing the Emacs standard notation
+for the input events in @var{sequence}.  The argument @var{sequence} may
+be a string, vector or list.  @xref{Input Events}, for more information
+about valid events.  See also the examples for
+@code{single-key-description}, below.
+@end defun
+
+@defun single-key-description event
+@cindex event printing
+@cindex character printing
+@cindex control character printing
+@cindex meta character printing
+This function returns a string describing @var{event} in the standard
+Emacs 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
+function key symbol appears as itself.  An event which 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 'C-mouse-1)
+     @result{} "C-mouse-1"
+@end group
+@end smallexample
+@end defun
+
+@defun text-char-description character
+This function returns a string describing @var{character} in the
+standard Emacs 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
+Emacs 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
+
+  Emacs provides a variety of on-line help functions, all accessible to
+the user as subcommands of the prefix @kbd{C-h}.  For more information
+about them, see @ref{Help, , Help, emacs, The GNU Emacs 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.
+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
+
+  The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
+but specifies 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
+@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 only the documentation strings,
+and only those of functions and variables that are included in Emacs
+when it is dumped.  If @var{do-all} is non-@code{nil}, it scans the
+names and documentation strings of all functions and variables.
+@end deffn
+
+@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 which is a message explaining 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
+Emacs recognizes as meaning Help.  By default, it is 8, which is
+@kbd{C-h}.  When Emacs 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.
+
+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{read-event} or @code{read-char} 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.
+@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
+
+@c Emacs 19 feature
+@defvar data-directory
+This variable holds the name of the directory in which Emacs finds
+certain documentation and text files that come with Emacs.  In older
+Emacs versions, @code{exec-directory} was used for this.
+@end defvar
+
+@c Emacs 19 feature
+@defmac make-help-screen fname help-line help-text help-map
+This macro defines a help command named @var{fname} which acts like a
+prefix key which 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 of 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 which 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
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/lispref/streams.texi	Wed Mar 16 19:53:19 1994 +0000
@@ -0,0 +1,713 @@
+@c -*-texinfo-*-
+@c This is part of the GNU Emacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c See the file elisp.texi for copying conditions.
+@setfilename ../info/streams
+@node Streams, Minibuffers, Debugging, Top
+@comment  node-name,  next,  previous,  up
+@chapter Reading and Printing Lisp Objects
+
+  @dfn{Printing} and @dfn{reading} are the operations of converting Lisp
+objects to textual form and vice versa.  They use the printed
+representations and read syntax described in @ref{Types of Lisp Object}.
+
+  This chapter describes the Lisp functions for reading and printing.
+It also describes @dfn{streams}, which specify where to get the text (if
+reading) or where to put it (if printing).
+
+@menu
+* Streams Intro::     Overview of streams, reading and printing.
+* Input Streams::     Various data types that can be used as input streams.
+* Input Functions::   Functions to read Lisp objects from text.
+* Output Streams::    Various data types that can be used as output streams.
+* Output Functions::  Functions to print Lisp objects as text.
+* Output Variables::  Variables that control what the printing functions do.
+@end menu
+
+@node Streams Intro
+@section Introduction to Reading and Printing
+@cindex Lisp reader
+@cindex printing
+@cindex reading
+
+  @dfn{Reading} a Lisp object means parsing a Lisp expression in textual
+form and producing a corresponding Lisp object.  This is how Lisp
+programs get into Lisp from files of Lisp code.  We call the text the
+@dfn{read syntax} of the object.  For example, the text @samp{(a .@: 5)}
+is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
+@sc{cdr} is the number 5.
+
+  @dfn{Printing} a Lisp object means producing text that represents that
+object---converting the object to its printed representation.  Printing
+the cons cell described above produces the text @samp{(a .@: 5)}.
+
+  Reading and printing are more or less inverse operations: printing the
+object that results from reading a given piece of text often produces
+the same text, and reading the text that results from printing an object
+usually produces a similar-looking object.  For example, printing the
+symbol @code{foo} produces the text @samp{foo}, and reading that text
+returns the symbol @code{foo}.  Printing a list whose elements are
+@code{a} and @code{b} produces the text @samp{(a b)}, and reading that
+text produces a list (but not the same list) with elements are @code{a}
+and @code{b}.
+
+  However, these two operations are not precisely inverses.  There are
+two kinds of exceptions:
+
+@itemize @bullet
+@item
+Printing can produce text that cannot be read.  For example, buffers,
+windows, frames, subprocesses and markers print into text that starts
+with @samp{#}; if you try to read this text, you get an error.  There is
+no way to read those data types.
+
+@item
+One object can have multiple textual representations.  For example,
+@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
+@samp{(a .@: (b))} represent the same list.  Reading will accept any of
+the alternatives, but printing must choose one of them.
+@end itemize
+
+@node Input Streams
+@section Input Streams
+@cindex stream (for reading)
+@cindex input stream
+
+  Most of the Lisp functions for reading text take an @dfn{input stream}
+as an argument.  The input stream specifies where or how to get the
+characters of the text to be read.  Here are the possible types of input
+stream:
+
+@table @asis
+@item @var{buffer}
+@cindex buffer input stream
+The input characters are read from @var{buffer}, starting with the
+character directly after point.  Point advances as characters are read.
+
+@item @var{marker}
+@cindex marker input stream
+The input characters are read from the buffer that @var{marker} is in,
+starting with the character directly after the marker.  The marker
+position advances as characters are read.  The value of point in the
+buffer has no effect when the stream is a marker.
+
+@item @var{string}
+@cindex string input stream
+The input characters are taken from @var{string}, starting at the first
+character in the string and using as many characters as required.
+
+@item @var{function}
+@cindex function input stream
+The input characters are generated by @var{function}, one character per
+call.  Normally @var{function} is called with no arguments, and should
+return a character.
+
+@cindex unreading
+Occasionally @var{function} is called with one argument (always a
+character).  When that happens, @var{function} should save the argument
+and arrange to return it on the next call.  This is called
+@dfn{unreading} the character; it happens when the Lisp reader reads one
+character too many and wants to ``put it back where it came from''.
+
+@item @code{t}
+@cindex @code{t} input stream
+@code{t} used as a stream means that the input is read from the
+minibuffer.  In fact, the minibuffer is invoked once and the text
+given by the user is made into a string that is then used as the
+input stream.
+
+@item @code{nil}
+@cindex @code{nil} input stream
+@code{nil} supplied as an input stream means to use the value of
+@code{standard-input} instead; that value is the @dfn{default input
+stream}, and must be a non-@code{nil} input stream.
+
+@item @var{symbol}
+A symbol as input stream is equivalent to the symbol's function
+definition (if any).
+@end table
+
+  Here is an example of reading from a stream which is a buffer, showing
+where point is located before and after:
+
+@example
+@group
+---------- Buffer: foo ----------
+This@point{} is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(read (get-buffer "foo"))
+     @result{} is
+@end group
+@group
+(read (get-buffer "foo"))
+     @result{} the
+@end group
+
+@group
+---------- Buffer: foo ----------
+This is the@point{} contents of foo.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+@noindent
+Note that the first read skips a space at the beginning of the buffer.
+Reading skips any amount of whitespace preceding the significant text.
+
+  In Emacs 18, reading a symbol discarded the delimiter terminating the
+symbol.  Thus, point would end up at the beginning of @samp{contents}
+rather than after @samp{the}.  The Emacs 19 behavior is superior because
+it correctly handles input such as @samp{bar(foo)}, where the delimiter
+that ends one object is needed as the beginning of another object.
+
+  Here is an example of reading from a stream that is a marker,
+initialized to point at the beginning of the buffer shown.  The value
+read is the symbol @code{This}.
+
+@example
+@group
+
+---------- Buffer: foo ----------
+This is the contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+@group
+(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
+     @result{} #<marker at 1 in foo>
+@end group
+@group
+(read m)
+     @result{} This
+@end group
+@group
+m
+     @result{} #<marker at 6 in foo>   ;; @r{After the first space.}
+@end group
+@end example
+
+  Here we read from the contents of a string:
+
+@example
+@group
+(read "(When in) the course")
+     @result{} (When in)
+@end group
+@end example
+
+  The following example reads from the minibuffer.  The
+prompt is: @w{@samp{Lisp expression: }}.  (That is always the prompt
+used when you read from the stream @code{t}.)  The user's input is shown
+following the prompt.
+
+@example
+@group
+(read t)
+     @result{} 23
+---------- Buffer: Minibuffer ----------
+Lisp expression: @kbd{23 @key{RET}}
+---------- Buffer: Minibuffer ----------
+@end group
+@end example
+
+  Finally, here is an example of a stream that is a function, named
+@code{useless-stream}.  Before we use the stream, we initialize the
+variable @code{useless-list} to a list of characters.  Then each call to
+the function @code{useless-stream} obtains the next characters in the list
+or unreads a character by adding it to the front of the list.
+
+@example
+@group
+(setq useless-list (append "XY()" nil))
+     @result{} (88 89 40 41)
+@end group
+
+@group
+(defun useless-stream (&optional unread)
+  (if unread
+      (setq useless-list (cons unread useless-list))
+    (prog1 (car useless-list)
+           (setq useless-list (cdr useless-list)))))
+     @result{} useless-stream
+@end group
+@end example
+
+@noindent
+Now we read using the stream thus constructed:
+
+@example
+@group
+(read 'useless-stream)
+     @result{} XY
+@end group
+
+@group
+useless-list
+     @result{} (41)
+@end group
+@end example
+
+@noindent
+Note that the close parenthesis remains in the list.  The reader has
+read it, discovered that it ended the input, and unread it.  Another
+attempt to read from the stream at this point would get an error due to
+the unmatched close parenthesis.
+
+@defun get-file-char
+This function is used internally as an input stream to read from the
+input file opened by the function @code{load}.  Don't use this function
+yourself.
+@end defun
+
+@node Input Functions
+@section Input Functions
+
+  This section describes the Lisp functions and variables that pertain
+to reading.
+
+  In the functions below, @var{stream} stands for an input stream (see
+the previous section).  If @var{stream} is @code{nil} or omitted, it
+defaults to the value of @code{standard-input}.
+
+@kindex end-of-file
+  An @code{end-of-file} error is signaled if reading encounters an
+unterminated list, vector or string.
+
+@defun read &optional stream
+This function reads one textual Lisp expression from @var{stream},
+returning it as a Lisp object.  This is the basic Lisp input function.
+@end defun
+
+@defun read-from-string string &optional start end
+@cindex string to object
+This function reads the first textual Lisp expression from the text in
+@var{string}.  It returns a cons cell whose @sc{car} is that expression,
+and whose @sc{cdr} is an integer giving the position of the next
+remaining character in the string (i.e., the first one not read).
+
+If @var{start} is supplied, then reading begins at index @var{start} in the
+string (where the first character is at index 0).  If @var{end} is also
+supplied, then reading stops at that index as if the rest of the string
+were not there.
+
+For example:
+
+@example
+@group
+(read-from-string "(setq x 55) (setq y 5)")
+     @result{} ((setq x 55) . 11)
+@end group
+@group
+(read-from-string "\"A short string\"")
+     @result{} ("A short string" . 16)
+@end group
+
+@group
+;; @r{Read starting at the first character.}
+(read-from-string "(list 112)" 0)
+     @result{} ((list 112) . 10)
+@end group
+@group
+;; @r{Read starting at the second character.}
+(read-from-string "(list 112)" 1)
+     @result{} (list . 6)
+@end group
+@group
+;; @r{Read starting at the seventh character,}
+;;   @r{and stopping at the ninth.}
+(read-from-string "(list 112)" 6 8)
+     @result{} (11 . 8)
+@end group
+@end example
+@end defun
+
+@defvar standard-input
+This variable holds the default input stream---the stream that
+@code{read} uses when the @var{stream} argument is @code{nil}.
+@end defvar
+
+@node Output Streams
+@section Output Streams
+@cindex stream (for printing)
+@cindex output stream
+
+  An output stream specifies what to do with the characters produced
+by printing.  Most print functions accept an output stream as an
+optional argument.  Here are the possible types of output stream:
+
+@table @asis
+@item @var{buffer}
+@cindex buffer output stream
+The output characters are inserted into @var{buffer} at point.
+Point advances as characters are inserted.
+
+@item @var{marker}
+@cindex marker output stream
+The output characters are inserted into the buffer that @var{marker}
+points into, at the marker position.  The position advances as
+characters are inserted.  The value of point in the buffer has no effect
+on printing when the stream is a marker.
+
+@item @var{function}
+@cindex function output stream
+The output characters are passed to @var{function}, which is responsible
+for storing them away.  It is called with a single character as
+argument, as many times as there are characters to be output, and is
+free to do anything at all with the characters it receives.
+
+@item @code{t}
+@cindex @code{t} output stream
+The output characters are displayed in the echo area.
+
+@item @code{nil}
+@cindex @code{nil} output stream
+@code{nil} specified as an output stream means to the value of
+@code{standard-output} instead; that value is the @dfn{default output
+stream}, and must be a non-@code{nil} output stream.
+
+@item @var{symbol}
+A symbol as output stream is equivalent to the symbol's function
+definition (if any).
+@end table
+
+  Here is an example of a buffer used as an output stream.  Point is
+initially located as shown immediately before the @samp{h} in
+@samp{the}.  At the end, point is located directly before that same
+@samp{h}.
+
+@cindex print example
+@example
+@group
+---------- Buffer: foo ----------
+This is t@point{}he contents of foo.
+---------- Buffer: foo ----------
+@end group
+
+(print "This is the output" (get-buffer "foo"))
+     @result{} "This is the output"
+
+@group
+---------- Buffer: foo ----------
+This is t
+"This is the output"
+@point{}he contents of foo.
+---------- Buffer: foo ----------
+@end group
+@end example
+
+  Now we show a use of a marker as an output stream.  Initially, the
+marker points in buffer @code{foo}, between the @samp{t} and the
+@samp{h} in the word @samp{the}.  At the end, the marker has been
+advanced over the inserted text so that it still points before the same
+@samp{h}.  Note that the location of point, shown in the usual fashion,
+has no effect.
+
+@example
+@group
+---------- Buffer: foo ----------
+"This is the @point{}output"
+---------- Buffer: foo ----------
+@end group
+
+@group
+m
+     @result{} #<marker at 11 in foo>
+@end group
+
+@group
+(print "More output for foo." m)
+     @result{} "More output for foo."
+@end group
+
+@group
+---------- Buffer: foo ----------
+"This is t
+"More output for foo."
+he @point{}output"
+---------- Buffer: foo ----------
+@end group
+
+@group
+m
+     @result{} #<marker at 35 in foo>
+@end group
+@end example
+
+  The following example shows output to the echo area:
+
+@example
+@group
+(print "Echo Area output" t)
+     @result{} "Echo Area output"
+---------- Echo Area ----------
+"Echo Area output"
+---------- Echo Area ----------
+@end group
+@end example
+
+  Finally, we show the use of a function as an output stream.  The
+function @code{eat-output} takes each character that it is given and
+conses it onto the front of the list @code{last-output} (@pxref{Building
+Lists}).  At the end, the list contains all the characters output, but
+in reverse order.
+
+@example
+@group
+(setq last-output nil)
+     @result{} nil
+@end group
+
+@group
+(defun eat-output (c)
+  (setq last-output (cons c last-output)))
+     @result{} eat-output
+@end group
+
+@group
+(print "This is the output" 'eat-output)
+     @result{} "This is the output"
+@end group
+
+@group
+last-output
+     @result{} (10 34 116 117 112 116 117 111 32 101 104
+    116 32 115 105 32 115 105 104 84 34 10)
+@end group
+@end example
+
+@noindent
+Now we can put the output in the proper order by reversing the list:
+
+@example
+@group
+(concat (nreverse last-output))
+     @result{} "
+\"This is the output\"
+"
+@end group
+@end example
+
+@node Output Functions
+@section Output Functions
+
+  This section describes the Lisp functions for printing Lisp objects.
+
+@cindex @samp{"} in printing
+@cindex @samp{\} in printing
+@cindex quoting characters in printing
+@cindex escape characters in printing
+  Some of the Emacs printing functions add quoting characters to the
+output when necessary so that it can be read properly.  The quoting
+characters used are @samp{"} and @samp{\}; they distinguish strings from
+symbols, and prevent punctuation characters in strings and symbols from
+being taken as delimiters.  @xref{Printed Representation}, for full
+details.  You specify quoting or no quoting by the choice of printing
+function.
+
+  If the text is to be read back into Lisp, then it is best to print
+with quoting characters to avoid ambiguity.  Likewise, if the purpose is
+to describe a Lisp object clearly for a Lisp programmer.  However, if
+the purpose of the output is to look nice for humans, then it is better
+to print without quoting.
+
+  Printing a self-referent Lisp object requires an infinite amount of
+text.  In certain cases, trying to produce this text leads to a stack
+overflow.  Emacs detects such recursion and prints @samp{#@var{level}}
+instead of recursively printing an object already being printed.  For
+example, here @samp{#0} indicates a recursive reference to the object at
+level 0 of the current print operation:
+
+@example
+(setq foo (list nil))
+     @result{} (nil)
+(setcar foo foo)
+     @result{} (#0)
+@end example
+
+  In the functions below, @var{stream} stands for an output stream.
+(See the previous section for a description of output streams.)  If
+@var{stream} is @code{nil} or omitted, it defaults to the value of
+@code{standard-output}.
+
+@defun print object &optional stream
+@cindex Lisp printer
+The @code{print} function is a convenient way of printing.  It outputs
+the printed representation of @var{object} to @var{stream}, printing in
+addition one newline before @var{object} and another after it.  Quoting
+characters are used.  @code{print} returns @var{object}.  For example:
+
+@example
+@group
+(progn (print 'The\ cat\ in)
+       (print "the hat")
+       (print " came back"))
+     @print{}
+     @print{} The\ cat\ in
+     @print{}
+     @print{} "the hat"
+     @print{}
+     @print{} " came back"
+     @print{}
+     @result{} " came back"
+@end group
+@end example
+@end defun
+
+@defun prin1 object &optional stream
+This function outputs the printed representation of @var{object} to
+@var{stream}.  It does not print any spaces or newlines to separate
+output as @code{print} does, but it does use quoting characters just
+like @code{print}.  It returns @var{object}.
+
+@example
+@group
+(progn (prin1 'The\ cat\ in)
+       (prin1 "the hat")
+       (prin1 " came back"))
+     @print{} The\ cat\ in"the hat"" came back"
+     @result{} " came back"
+@end group
+@end example
+@end defun
+
+@defun princ object &optional stream
+This function outputs the printed representation of @var{object} to
+@var{stream}.  It returns @var{object}.
+
+This function is intended to produce output that is readable by people,
+not by @code{read}, so it doesn't insert quoting characters and doesn't
+put double-quotes around the contents of strings.  It does not add any
+spacing between calls.
+
+@example
+@group
+(progn
+  (princ 'The\ cat)
+  (princ " in the \"hat\""))
+     @print{} The cat in the "hat"
+     @result{} " in the \"hat\""
+@end group
+@end example
+@end defun
+
+@defun terpri &optional stream
+@cindex newline in print
+This function outputs a newline to @var{stream}.  The name stands
+for ``terminate print''.
+@end defun
+
+@defun write-char character &optional stream
+This function outputs @var{character} to @var{stream}.  It returns
+@var{character}.
+@end defun
+
+@defun prin1-to-string object &optional noescape
+@cindex object to string
+This function returns a string containing the text that @code{prin1}
+would have printed for the same argument.
+
+@example
+@group
+(prin1-to-string 'foo)
+     @result{} "foo"
+@end group
+@group
+(prin1-to-string (mark-marker))
+     @result{} "#<marker at 2773 in strings.texi>"
+@end group
+@end example
+
+If @var{noescape} is non-@code{nil}, that inhibits use of quoting
+characters in the output.  (This argument is supported in Emacs versions
+19 and later.)
+
+@example
+@group
+(prin1-to-string "foo")
+     @result{} "\"foo\""
+@end group
+@group
+(prin1-to-string "foo" t)
+     @result{} "foo"
+@end group
+@end example
+
+See @code{format}, in @ref{String Conversion}, for other ways to obtain
+the printed representation of a Lisp object as a string.
+@end defun
+
+@node Output Variables
+@section Variables Affecting Output
+
+@defvar standard-output
+The value of this variable is the default output stream---the stream
+that print functions use when the @var{stream} argument is @code{nil}.
+@end defvar
+
+@defvar print-escape-newlines
+@cindex @samp{\n} in print
+@cindex escape characters
+If this variable is non-@code{nil}, then newline characters in strings
+are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
+Normally these characters are printed as actual newlines and formfeeds.
+
+This variable affects the print functions @code{prin1} and @code{print},
+as well as everything that uses them.  It does not affect @code{princ}.
+Here is an example using @code{prin1}:
+
+@example
+@group
+(prin1 "a\nb")
+     @print{} "a
+     @print{} b"
+     @result{} "a
+b"
+@end group
+
+@group
+(let ((print-escape-newlines t))
+  (prin1 "a\nb"))
+     @print{} "a\nb"
+     @result{} "a
+b"
+@end group
+@end example
+
+@noindent
+In the second expression, the local binding of
+@code{print-escape-newlines} is in effect during the call to
+@code{prin1}, but not during the printing of the result.
+@end defvar
+
+@defvar print-length
+@cindex printing limits
+The value of this variable is the maximum number of elements of a list
+that will be printed.  If a list being printed has more than this many
+elements, then it is abbreviated with an ellipsis.
+
+If the value is @code{nil} (the default), then there is no limit.
+
+@example
+@group
+(setq print-length 2)
+     @result{} 2
+@end group
+@group
+(print '(1 2 3 4 5))
+     @print{} (1 2 ...)
+     @result{} (1 2 ...)
+@end group
+@end example
+@end defvar
+
+@defvar print-level
+The value of this variable is the maximum depth of nesting of
+parentheses that will be printed.  Any list or vector at a depth
+exceeding this limit is abbreviated with an ellipsis.  A value of
+@code{nil} (which is the default) means no limit.
+
+This variable exists in version 19 and later versions.
+@end defvar