[PATCH] Pedantic corrections in macro docs

[Jean Abou Samra <jean@abou-samra.fr>]

[-- Attachment #1: Type: text/plain, Size: 3168 bytes --]

As it turns out, syntax-rules have more power than one might think.



From d026b3f2364754b559acf9ad8ec7129eddfb51c7 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra <jean@abou-samra.fr>
Date: Fri, 7 Jul 2023 16:40:06 +0200
Subject: [PATCH] Pedantic corrections in macro docs

---
 doc/ref/api-macros.texi | 28 ++++++++++++++++++----------
 1 file changed, 18 insertions(+), 10 deletions(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index a353719cb..d0ba892f0 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -435,13 +435,18 @@ For a formal definition of @code{syntax-rules} and its
pattern language, see
 @xref{Macros, , Macros, r5rs, Revised(5) Report on the Algorithmic Language
 Scheme}.
 
-@code{syntax-rules} macros are simple and clean, but do they have limitations.
-They do not lend themselves to expressive error messages: patterns either match
-or they don't. Their ability to generate code is limited to template-driven
-expansion; often one needs to define a number of helper macros to get real work
-done. Sometimes one wants to introduce a binding into the lexical context of
the
-generated code; this is impossible with @code{syntax-rules}. Relatedly, they
-cannot programmatically generate identifiers.
+@code{syntax-rules} macros are simple and clean, but do they have
+limitations.  They do not lend themselves to expressive error messages:
+patterns either match or they don't. Their ability to generate code is
+limited to template-driven expansion; often one needs to define a number
+of helper macros to get real work done. Sometimes one wants to introduce
+a binding into the lexical context of the generated code; this is very
+difficult with @code{syntax-rules}@footnote{It is in fact surprising
+that this is possible at all. See Oleg Kiselyov paper
+@uref{https://okmij.org/ftp/Scheme/macros.html#dirty-macros,How to Write
+Seemingly Unhygienic and Referentially Opaque Macros with
+Syntax-rules}. Relatedly, they cannot programmatically generate
+identifiers.
 
 The solution to all of these problems is to use @code{syntax-case} if you need
 its features. But if for some reason you're stuck with @code{syntax-rules}, you
@@ -581,9 +586,12 @@ verbose, which is true. But there is a difference:
@code{syntax-case} creates
 @emph{procedural} macros, giving the full power of Scheme to the macro
expander.
 This has many practical applications.
 
-A common desire is to be able to match a form only if it is an identifier. This
-is impossible with @code{syntax-rules}, given the datum matching forms. But
with
-@code{syntax-case} it is easy:
+A common desire is to be able to match a form only if it is an
+identifier. This is difficult with @code{syntax-rules}, given the datum
+matching forms@footnote{See
+@uref{https://okmij.org/ftp/Scheme/macros.html#macro-symbol-p, How to
+write @code{symbol?} with syntax-rules} on Oleg Kiselyov's
+website.}. But with @code{syntax-case} it is easy:
 
 @deffn {Scheme Procedure} identifier? syntax-object
 Returns @code{#t} if @var{syntax-object} is an identifier, or @code{#f}
-- 
2.40.1



[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 228 bytes --]