* txr.1: Documented print, pprint, tostring and tostringp.

1 files changed, 36 insertions, 0 deletions

diff --git a/txr.1 b/txr.1
index e41c1f3c..138e43ac 100644
--- a/txr.1
+++ b/txr.1
@@ -7900,6 +7900,42 @@ truncated off entirely, including the decimal point.
 
 .SS Functions print, pprint, tostring, tostringp
 
+.TP
+Syntax:
+
+  (print <obj> [<stream>])
+  (pprint <obj> [<stream>])
+  (tostring <obj>)
+  (tostringp <obj>)
+
+.TP
+Description:
+
+The print and pprint functions render a printed character representation of the
+obj argument into a stream. If a stream argument is not supplied, then 
+the destination is the stream currently stored in the *standard-output*
+variable. The print function renders in a way which strives for read-print
+consistency: an object is printed in a notation which is recognized as
+a similar object of the same kind when it appears in TXR source code.
+The pprint function ("pretty print") does not strive for read-print consistency.
+For instance it prints a string object simply by dumping its characters, rather
+than by adding the surrounding quotes and rendering escape syntax for
+special characters.
+
+The tostring and tostringp functions are like print and pprint, but
+they do not accept a stream argument, instead printing to a freshly
+instantiated string stream, and returning the resulting string.
+
+The following equivalences hold between calls to the format function
+and calls to these functions:
+
+  (format stream "~s" obj)  <-->  (print obj stream)
+  (format t "~s" obj)       <-->  (print obj)
+  (format nil "~s" obj)     <-->  (tostring obj)
+
+For pprint and tostringp, the equivalence is produced by using "~a"
+in format rather than "~s".
+
 .SS Function make-string-input-stream
 
 .SS Function make-string-byte-input-stream