From 0bd9494ea0801a5f07ac785c0df724c893373c13 Mon Sep 17 00:00:00 2001
From: Kaz Kylheku <kaz@kylheku.com>
Date: Tue, 28 Jul 2015 07:33:19 -0700
Subject: * txr.1: In introduction of user-defined places, mentioning placelet
 as a way of writing place update macros. Example added under placelet.

---
 ChangeLog |  6 ++++++
 txr.1     | 34 ++++++++++++++++++++++++++++++++--
 2 files changed, 38 insertions(+), 2 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 141e1694..7de372ed 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2015-07-28  Kaz Kylheku  <kaz@kylheku.com>
+
+	* txr.1: In introduction of user-defined places, mentioning
+	placelet as a way of writing place update macros.
+	Example added under placelet.
+
 2015-07-25  Kaz Kylheku  <kaz@kylheku.com>
 
 	Version 110.
diff --git a/txr.1 b/txr.1
index 3ad7c61a..a9e46876 100644
--- a/txr.1
+++ b/txr.1
@@ -9937,7 +9937,8 @@ macro, or possibly the
 .code define-place-macro
 macro in simple cases when a new syntactic place can be expressed as a
 transformation to the syntax of an existing place.
-New place update macros (place operators) are written using the
+Three ways exist for developing new place update macros (place operators).
+They can be written using the ordinary macro definer
 ordinary macro definer
 .codn defmacro ,
 with the help of special utility macros called
@@ -9945,6 +9946,12 @@ with the help of special utility macros called
 .codn with-clobber-expander ,
 and
 .codn with-delete-expander .
+They can also be written using
+.code defmacro
+in conjunction with the operators
+.code placelet
+or
+.codn placelet* .
 Simple update macros similar to
 .code inc
 and
@@ -25512,7 +25519,9 @@ This variable is initialized to 0. Each time the
 .code gensym
 function is called,
 it is incremented. The incremented value forms the basis of the numeric
-suffix which gensym uses to form the name of the new symbol.
+suffix which
+.code gensym
+uses to form the name of the new symbol.
 
 .coNP Function @ make-package
 .synb
@@ -29136,6 +29145,27 @@ Rather it may be substituted by one kind of form when it
 is treated as a pure value, and another kind of form
 when it is treated as a place.
 
+.TP* "Example:"
+
+Implementation of
+.code inc
+using
+.codn placelet :
+
+.cblk
+  (defmacro inc (place : (delta 1))
+    (with-gensyms (p)
+      ^(placelet ((,p ,place))
+         (set ,p (+ ,p ,delta)))))
+.cble
+
+The gensym
+.code p
+is used to avoid accidental capture of references
+emanating from the
+.code delta
+form.
+
 .coNP Operators @ tree-bind and @ mac-param-bind
 .synb
 .mets (tree-bind < macro-style-params < expr << form *)
-- 
cgit v1.2.3