bug#58646: [PATCH] doc: Fix eval-when example

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

 From 0e35d0494b7c6f05819e3386d404776a64a2e5c9 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra <jean@abou-samra.fr>
Date: Wed, 19 Oct 2022 23:01:06 +0200
Subject: [PATCH] doc: Fix eval-when example

* doc/ref/api-macros.texi: make the macro expand to the literal
   date, not to a call to the date function.  The example previously
   did not actually need eval-when and did not show the intended
   effect.
---
  doc/ref/api-macros.texi | 25 ++++++++++++++++---------
  1 file changed, 16 insertions(+), 9 deletions(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index cdb33df31..ed7bbe763 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -1236,14 +1236,19 @@ But if a syntactic definition needs to call out 
to a normal procedure at
  expansion-time, it might well need need special declarations to 
indicate that
  the procedure should be made available at expansion-time.

-For example, the following code will work at a REPL, but not in a file:
+For example, the following code tries to embed a compilation timestamp
+in the compiled bytecode using a macro that expands to the date as
+string literal.  It will work at a REPL, but in a file, it cannot be
+byte-compiled.

  @example
-;; incorrect
  (use-modules (srfi srfi-19))
-(define (date) (date->string (current-date)))
-(define-syntax %date (identifier-syntax (date)))
-(define *compilation-date* %date)
+(define start-date (date->string (current-date)))
+(define-syntax *compilation-date*
+  (lambda (sintax)
+    start-date))
+(display *compilation-date*)
+(newline)
  @end example

  It works at a REPL because the expressions are evaluated one-by-one, 
in order,
@@ -1253,12 +1258,14 @@ evaluated until the compiled file is loaded.
  The fix is to use @code{eval-when}.

  @example
-;; correct: using eval-when
  (use-modules (srfi srfi-19))
  (eval-when (expand load eval)
-  (define (date) (date->string (current-date))))
-(define-syntax %date (identifier-syntax (date)))
-(define *compilation-date* %date)
+  (define start-date (date->string (current-date))))
+(define-syntax *compilation-date*
+  (lambda (sintax)
+    start-date))
+(display *compilation-date*)
+(newline)
  @end example

  @deffn {Syntax} eval-when conditions exp...
-- 
2.37.3