[Guile-commits] 02/03: Document quote-syntax

[Andy Wingo]

wingo pushed a commit to branch master
in repository guile.

commit c97e1fbb53d64925465ca3333dce511b06cff383
Author: Andy Wingo <wingo@pobox.com>
AuthorDate: Tue Mar 9 20:49:46 2021 +0100

    Document quote-syntax
    
    * NEWS: Update.
    * doc/ref/api-macros.texi (Syntax Case): Update.
---
 NEWS                    |  9 +++++++--
 doc/ref/api-macros.texi | 18 ++++++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/NEWS b/NEWS
index 40760ea..d985a0d 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 23f9a13..14e0852 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