text produces a list (but not the same list) with elements @code{a}
and @code{b}.
- However, these two operations are not precisely inverses. There are
-three kinds of exceptions:
+ However, these two operations are not precisely inverse to each other.
+There are three kinds of exceptions:
@itemize @bullet
@item
@end example
@noindent
-Note that the open and close parentheses remains in the list. The Lisp
+Note that the open and close parentheses remain in the list. The Lisp
reader encountered the open parenthesis, decided that it ended the
input, and unread it. Another attempt to read from the stream at this
point would read @samp{()} and return @code{nil}.
The output characters are inserted into the buffer that @var{marker}
points into, at the marker position. The marker position advances as
characters are inserted. The value of point in the buffer has no effect
-on printing when the stream is a marker.
+on printing when the stream is a marker, and this kind of printing
+does not move point.
@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.
+argument, as many times as there are characters to be output, and
+is responsible for storing the characters wherever you want to put them.
@item @code{t}
@cindex @code{t} output stream
@item @code{nil}
@cindex @code{nil} output stream
-@code{nil} specified as an output stream means to the value of
+@code{nil} specified as an output stream means to use the value of
@code{standard-output} instead; that value is the @dfn{default output
-stream}, and must be a non-@code{nil} output stream.
+stream}, and must not be @code{nil}.
@item @var{symbol}
A symbol as output stream is equivalent to the symbol's function
@cindex print example
@example
-@group
-(setq m (set-marker (make-marker) 10 (get-buffer "foo")))
- @result{} #<marker at 10 in foo>
-@end group
-
@group
---------- Buffer: foo ----------
This is t@point{}he contents of foo.
(print "This is the output" (get-buffer "foo"))
@result{} "This is the output"
-@group
-m
- @result{} #<marker at 32 in foo>
-@end group
@group
---------- Buffer: foo ----------
This is t
@example
@group
---------- Buffer: foo ----------
-"This is the @point{}output"
+This is the @point{}output
---------- Buffer: foo ----------
@end group
@group
-m
- @result{} #<marker at 11 in foo>
+(setq m (copy-marker 10))
+ @result{} #<marker at 10 in foo>
@end group
@group
@group
---------- Buffer: foo ----------
-"This is t
+This is t
"More output for foo."
-he @point{}output"
+he @point{}output
---------- Buffer: foo ----------
@end group
@group
m
- @result{} #<marker at 35 in foo>
+ @result{} #<marker at 34 in foo>
@end group
@end example
purpose of the output is to look nice for humans, then it is usually
better to print without quoting.
- Printing a self-referent Lisp object in the normal way would require
-an infinite amount of text, and could even result in 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:
+ Lisp objects can refer to themselves. Printing a self-referential
+object in the normal way would require an infinite amount of text, and
+the attempt could cause infinite recursion. 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))
the printed representation of a Lisp object as a string.
@end defun
-@tindex with-output-to-string
@defmac with-output-to-string body...
-This macro executes the @var{body} forms with standard-output set up so
-that all output feeds into a string. Then it returns that string.
+@tindex with-output-to-string
+This macro executes the @var{body} forms with @code{standard-output} set
+up to feed output into a string. Then it returns that string.
For example, if the current buffer name is @samp{foo},
@code{prin1}, but not during the printing of the result.
@end defvar
+@tindex print-escape-nonascii
+@defvar print-escape-nonascii
+If this variable is non-@code{nil}, then unibyte non-@sc{ascii}
+characters in strings are unconditionally printed as backslash sequences
+by the print functions @code{prin1} and @code{print} that print with
+quoting.
+
+Those functions also use backslash sequences for unibyte non-@sc{ascii}
+characters, regardless of the value of this variable, when the output
+stream is a multibyte buffer or a marker pointing into one.
+@end defvar
+
+@tindex print-escape-multibyte
+@defvar print-escape-multibyte
+If this variable is non-@code{nil}, then multibyte non-@sc{ascii}
+characters in strings are unconditionally printed as backslash sequences
+by the print functions @code{prin1} and @code{print} that print with
+quoting.
+
+Those functions also use backslash sequences for multibyte
+non-@sc{ascii} characters, regardless of the value of this variable,
+when the output stream is a unibyte buffer or a marker pointing into
+one.
+@end defvar
+
@defvar print-length
@cindex printing limits
The value of this variable is the maximum number of elements to print in
parentheses and brackets when 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.
+@end defvar
+
+ These variables are used for detecting and reporting circular
+and shared structure---but they are only defined in Emacs 21.
+
+@tindex print-circle
+@defvar print-circle
+If non-@code{nil}, this variable enables detection of circular
+and shared structure in printing.
+@end defvar
+
+@tindex print-gensym
+@defvar print-gensym
+If non-@code{nil}, this variable enables detection of uninterned symbols
+(@pxref{Creating Symbols}) in printing. When this is enabled,
+uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
+reader to produce an uninterned symbol.
@end defvar