1 files changed, 111 insertions, 0 deletions
diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 8de5fe7..bdbbc5b 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -764,6 +764,117 @@ symbol as an argument instead of a cons, in which case they return
   car(cons(box(abc), box(def))) => ;; Awk undefined value
 .ft R
 
+.SS Function \fIsexp\fP
+.bk
+.B Syntax:
+
+.ft B
+  sexp(x)
+.ft R
+
+.B Description
+The
+.B sexp
+function produces a printed representation of a Lisp object: an
+.IR "S-expression" .
+This form reveals the structure in a readable format.
+It is returned as a string.
+
+String objects, boxed or unboxed, are rendered with double quotes. Any double
+quotes or backslash character appearing in the string is preceded
+with a backslash.
+
+Symbols are rendered without surrounding quotes, but with the same escaping
+scheme. The nil symbol appears as
+.BR nil .
+
+A boxed undefined value appears as
+.BR #U .
+
+Cons cells are printed in a parenthesized notation, according
+to these rules:
+
+.IP 1.
+A cons cell whose
+.I cdr
+is an atom other than
+.B nil
+is printed in the
+.I "dotted pair"
+notation as
+.BI ( "a " . " b" )
+where
+.I a
+and
+.I d
+are the recursively calculated S-expressions of the
+.I car
+and
+.I cdr
+fields. The dot between the
+.I a
+and
+.I b
+is called the
+.IR "consing dot" .
+
+.IP 2
+A cons cell
+.I cdr
+is the atom
+.B nil
+is printed more compactly as
+.BI ( a )
+where
+.I a
+is the recursively calculated S-expression of the
+.I car
+field.
+
+.IP 3
+Whenever a cons cell
+appears as the
+.I cdr
+child of another cons cell, the parentheses of the child
+are removed, as is the consing dot before it, merging
+it with the parent. This rule is applied to the maximum extent
+possible. Visually, this means that where the S-expression
+.BI ( a " . (" "b ..." ))
+would be produced, the dot and inner parentheses disappear,
+resulting instead in
+.BI ( a
+.IB "b ..." ).
+.PP
+Rules 2 and 3 result in an understandable notation for lists.
+For instance, if full use of the dotted pair notation is
+made, the list of three numbers 1, 2, 3 appears like this:
+.BR "(1 . (2  .  (3  .  nil)))" .
+Rule 2 reduces it slightly to
+.BR "(1 . (2  .  (3)))" .
+A single application application of rule 3 produces
+.BR "(1 . (2 3))" ,
+and one more application of the rule results in
+.BR "(1 2 3)" .
+All these representations are equivalent, denoting exactly the same data
+structure. The
+.B sexp
+function favors the last of these.
+
+.B Examples:
+
+.ft B
+  BEGIN {
+    print sexp("abc")
+    print sexp(cons(1, cons(2, 3)))
+    print sexp(cons("a", cons(2, box(undef))))
+    print cons(nil, 1)
+  }
+  "abc"
+  (1 2 . 3)
+  ("a" 2 . #U)
+  (nil . 1)
+.ft R
+
 .SH "SEE ALSO"
 
 cppawk(1)