add section on toplevel expansion to r6rs incompatibilities

* doc/ref/r6rs.texi (R6RS Incompatibilities): Add a section about
  toplevel expansion, before taking a look at fixing it...

1 files changed, 44 insertions, 0 deletions

diff --git a/doc/ref/r6rs.texi b/doc/ref/r6rs.texi
index 6c5637e19..a680f51c2 100644
--- a/doc/ref/r6rs.texi
+++ b/doc/ref/r6rs.texi
@@ -40,6 +40,50 @@ does not restore it.  This is a bug.
 A @code{set!} to a variable transformer may only expand to an 
 expression, not a definition---even if the original @code{set!} 
 expression was in definition context.
+
+@item
+Instead of using the algorithm detailed in chapter 10 of the R6RS,
+expansion of toplevel forms happens sequentially.
+
+For example, while the expansion of the following set of recursive
+nested definitions does do the correct thing:
+
+@example
+(let ()
+  (define even?
+    (lambda (x)
+      (or (= x 0) (odd? (- x 1)))))
+  (define-syntax odd?
+    (syntax-rules ()
+      ((odd? x) (not (even? x)))))
+  (even? 10))
+@result{} #t
+@end example
+
+@noindent
+The same definitions at the toplevel do not:
+
+@example
+(begin
+ (define even?
+   (lambda (x)
+     (or (= x 0) (odd? (- x 1)))))
+ (define-syntax odd?
+   (syntax-rules ()
+     ((odd? x) (not (even? x)))))
+ (even? 10))
+<unnamed port>:4:18: In procedure even?:
+<unnamed port>:4:18: Wrong type to apply: #<syntax-transformer odd?>
+@end example
+
+This is because when expanding the right-hand-side of @code{even?}, the
+reference to @code{odd?} is not yet marked as a syntax transformer, so
+it is assumed to be a function.
+
+While it is likely that we can fix the case of toplevel forms nested in
+a @code{begin} or a @code{library} form, a fix for toplevel programs
+seems trickier to implement in a backward-compatible way. Suggestions
+and/or patches would be appreciated.
 @end itemize
 
 @node R6RS Standard Libraries