1 files changed, 87 insertions, 1 deletions
diff --git a/cppawk-cons.1 b/cppawk-cons.1
index 5b239cd..2c11c4d 100644
--- a/cppawk-cons.1
+++ b/cppawk-cons.1
@@ -128,7 +128,7 @@ cons \- Lisp-like data representation and control flow macros
 
   \fI// procedural list construction\fP
 
-  \fIbag\fP = list_create()
+  \fIbag\fP = list_begin()
   \fIbag\fP = list_add(\fIbag\fP, \fIitem\fP)
   \fIlist\fP = list_end(\fIbag\fP)
 
@@ -2224,6 +2224,92 @@ has the same effect as
   }
 .ft R
 
+.SH PROCEDURAL LIST CONSTRUCTION
+.bk
+.SS Macros \fIlist_begin\fP, \fIlist_add\fP, \fIlist_end\fP and \fIlist_end_atom\fP
+.bk
+Syntax:
+
+.ft B
+  \fIbag\fP = list_begin()
+  \fIbag\fP = list_add(\fIbag\fP, \fIitem\fP)
+  \fIlist\fP = list_end(\fIbag\fP)
+  \fIlist\fP = list_end_atom(\fIbag\fP, \fIatom\fP)
+.ft R
+
+.B Description
+
+These macros are used for building lists procedurally, by adding items
+from left to right.
+
+.IP \fBlist_begin\fP
+This macro takes no arguments and returns a bag object. This object is
+not itself a list. Rather, a list is produced from a bag object
+using the
+.B list_end
+macro or the
+.B list_end_atom
+macro.
+
+.IP \fBlist_add\fP
+Evaluates the
+.I bag
+and
+.I item
+expressions. Then returns a new bag which contains
+all the same items as
+.I bag
+in the same order, plus
+.I item
+as the new rightmost element.
+The
+.I bag
+object isn't modified.
+
+.IP \fBlist_end\fP
+Converts
+.I bag
+into a list of items, which is returned. The
+.I bag
+object is unmodified.
+
+.IP \fBlist_end_atom\fP
+Converts
+.I bag
+into a list of items, which is returned. The
+.I bag
+object is unmodified.
+The list of items is terminated by the value of the
+.I atom
+expression. In spite of the naming, this need not
+be the atom. Simply, the last cons cell of the
+returned list has
+.I atom
+in its
+.I cdr
+field. If
+.I bag
+is empty, then
+.I atom
+is returned.
+.PP
+
+.B Examples:
+
+.ft B
+  \fIbag\fP = list_begin()
+
+  list_end(\fIbag\fP) -> nil
+  list_end_atom(\fIbag\fP, 3) -> 3
+
+  \fIbag\fP = list_add(\fIbag\fP, "a")
+  \fIbag\fP = list_add(\fIbag\fP, 1)
+  \fIbag\fP = list_add(\fIbag\fP, 2)
+
+  list_end(\fIbag\fP) -> ("a" 1 2)
+  list_end_atom(\fIbag\fP, 3) -> ("a" 1 2 . 3)
+.ft R
+
 .SH "SEE ALSO"
 
 cppawk(1), cppawk-fun(1)