Document quote-syntax

* NEWS: Update.
* doc/ref/api-macros.texi (Syntax Case): Update.

2 files changed, 25 insertions, 2 deletions

diff --git a/NEWS b/NEWS
index 40760ea51..d985a0df0 100644
--- a/NEWS
+++ b/NEWS
@@ -138,6 +138,10 @@ The Gnulib compatibility library has been updated, for the first time
 since 2017 or so.  We expect no functional change but look forward to
 any bug reports.
 
+** Optimized "eof-object?"
+
+This predicate is now understood by the compiler.
+
 * New interfaces and functionality
 
 ** `call-with-port'
@@ -168,10 +172,11 @@ similar, which will eventually be deprecated.
 
 See "Annotated Scheme Read" in the manual.
 
-** `syntax-sourcev'
 ** `quote-syntax'
 
-** Optimized "eof-object?"
+See "Syntax Case" in the manual.
+
+** `syntax-sourcev'
 
 * Bug fixes
 
diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index 23f9a13ef..14e085210 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -799,6 +799,24 @@ Note that @code{with-ellipsis} does not affect the ellipsis identifier
 of the generated code, unless @code{with-ellipsis} is included around
 the generated code.
 
+@subsubsection Syntax objects can be data too
+
+Generally speaking, you want the macro expander to pick apart all syntax
+objects in a source term.  The source and scope annotations attached to
+the syntax object are of interest to how the macro expander computes the
+result, but no syntax object itself should appear in the expanded
+term---usually.  Sometimes, though, a macro will want a syntax object to
+appear in the expanded output.  Normally you would just use @code{quote}
+to introduce the syntax object as a value, but the expander strips
+syntax objects from subexpression of @code{quote}.  For this rare use
+case, Guile has @code{quote-syntax}, which does not strip its
+subexpression.
+
+@deffn {Syntax} quote-syntax form
+Expand to the syntax object @code{form}, as a constant literal.  Like
+@code{quote}, but without calling @code{syntax->datum}.
+@end deffn
+
 @node Syntax Transformer Helpers
 @subsection Syntax Transformer Helpers