[cl-debian] Bug#403973: cl-utilities: write a better documentation for once-only

[Pierre THIERRY]

Package: cl-utilities
Version: 1.2.4-1
Severity: minor
Tags: patch

The documentation for the once-only macro should be written instead of
pointing to a newsgroup discussion describing it. Here is a patch that
adds the relevant description:

Index: Source/doc/once-only.html
===================================================================
--- Source.orig/doc/once-only.html	2006-08-06 23:22:30.480823552 +0200
+++ Source/doc/once-only.html	2006-08-06 23:33:13.696039976 +0200
@@ -11,29 +11,57 @@
 
 <p>
 
-<p><b>once-only</b> <i>(name*) form*</i>
+<p><b>once-only</b> <i>(name*) body-form*</i>
 <p>
 <p><b>Arguments and Values:</b><p>
 <p>
 <i>name</i>---a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/glo_s.html#symbol"><i>symbol</i></a></a>. <p>
 
-<i>form</i>---a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/glo_f.html#form"><i>form</i></a></a>. <p>
+<i>body-form</i>---a <a href="http://www.lispworks.com/documentation/HyperSpec/Body/glo_f.html#form"><i>form</i></a></a>. <p>
 
 <p>
 <p><b>Description:</b><p>
 <p>Meant to be used in macro code, <b>once-only</b> guards against
-multiple evaluation of its arguments in macroexpansion code. Any
-concise description would be far too vague to grasp, but <a
-href="http://groups.google.com/group/comp.lang.lisp/browse_frm/thread/1783554653afad7f/f6357129c8c1c002?rnum=1&_done=%2Fgroup%2Fcomp.lang.lisp%2Fbrowse_frm%2Fthread%2F1783554653afad7f%2F940b6ebd2d1757f4%3F#doc_f6357129c8c1c002">this
-thread on comp.lang.lisp</a> does a decent job of explaining what
-<b>once-only</b> does.
-
-<p><p><b>Notes:</b></p>
-
-<p>The description here is frustratingly non-descriptive, and I
-apologize for that. If you understand <b>once-only</b> and can give a
-better explanation, I would be very grateful—not to mention
-completely awed.
+multiple evaluation of its arguments in macroexpansion code.</p>
+
+<p><b>once-only</b> generates a Lisp form that evaluates each lexical
+variable named by the symbols given as <i>name</i> arguments to
+once-only, and evaluates the body forms in a lexical environment where
+these results are bound to their respective originating symbol.</p>
+
+<p>That is, if the only <i>name</i> argument were the single 'alpha
+symbol, the body forms would be evaluated in a lexical environment
+where 'alpha is bound to the result of the evaluation of alpha in the
+lexical environment of the generated Lisp form.</p>
+
+<p>Example:</p>
+
+<p>With the following 3x macro:</p>
+
+<pre>(defmacro 3x (x)
+  `(+ ,x ,x ,x))</pre>
+
+<p>These three forms evaluate to the same result because the form
+given as <i>x</i> argument is referencially transparent (i.e. it
+yields the same result each time it's evaluated):</p>
+
+<pre>(3x 2) === 6
+(3x (1+ 1)) === 6
+(let ((a 1)) (3x (1+ a))) === 6</pre>
+
+<p>But the following form has an argument that has side-effects and has different results for each of the three
+times it will be evaluated:</p>
+
+<pre>(let ((a 1)) (3x (incf a))) === 9</pre>
+
+<p>The problem is solved by protecting the body of the macro with
+once-only:</p>
+
+<pre>(defmacro 3x (x)
+  (once-only (x)
+    `(+ ,x ,x ,x)))
+
+(let ((a 1)) (3x (incf a))) === 6</pre>
 
 <p class="footer"><hr><a href="index.html">Manual Index</a></p>
 
It applies to 1.2.4-1.


-- System Information:
Debian Release: 4.0
  APT prefers testing
  APT policy: (990, 'testing'), (501, 'stable'), (500, 'unstable'), (500, 'stable')
Architecture: i386 (i686)
Shell:  /bin/sh linked to /bin/bash
Kernel: Linux 2.6.17-2-k7
Locale: LANG=fr_FR at euro, LC_CTYPE=fr_FR at euro (charmap=ISO-8859-15)

Versions of packages cl-utilities depends on:
ii  common-lisp-controller        6.8        This is a Common Lisp source and c

cl-utilities recommends no packages.

-- no debconf information

-- 
nowhere.man at levallois.eu.org
OpenPGP 0xD9D50D8A
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: Digital signature
URL: <https://mailman.common-lisp.net/pipermail/cl-debian/attachments/20061221/1b6532c3/attachment.sig>