Re: Doc patches outstanding

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

[-- Attachment #1.1.1: Type: text/plain, Size: 1043 bytes --]

Le 11/12/2022 à 03:05, Dr. Arne Babenhauserheide a écrit :
> Hi,
>
> Jean Abou Samra <jean@abou-samra.fr> writes:
>> I submitted a few doc patches which are awaiting someone
>> to review / push. They should be simple :-)  I hope someone
>> can have a look.
>>
>>
>> - Document that eq?, eqv? and equal? take any number
>>    of arguments.
>>
>> https://lists.gnu.org/archive/html/guile-devel/2022-11/msg00009.html
> I reviewed and pushed this. It took a bit longer than expected, because
> my git didn’t apply them cleanly to the main branch (I copied them from
> the archive website which turned out to be a bad idea), so I had to do
> most of that manually.
>
> I plan to take a look at the other two soon.




Aargh, it looks like there is some whitespace mangling at some
point between my mail client and debbugs, preventing the patches
from being applied as-is.

Thank you for applying the first one nevertheless. I am attaching
patch files for the other two, that should work better.

Best,
Jean


[-- Attachment #1.1.2: 0001-doc-Fix-eval-when-example.patch --]
[-- Type: text/x-patch, Size: 2853 bytes --]

From 759da55e72bb313ad5565c8502f7cd98a1454b93 Mon Sep 17 00:00:00 2001
From: Jean Abou Samra <jean@abou-samra.fr>
Date: Sun, 11 Dec 2022 12:26:18 +0100
Subject: [PATCH 1/2] 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 | 29 ++++++++++++++++++-----------
 1 file changed, 18 insertions(+), 11 deletions(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index cdb33df31..a353719cb 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -63,7 +63,7 @@ transformers, consider the following example macro definition:
          (begin exp ...)))))
 
 (when #t
-  (display "hey ho\n") 
+  (display "hey ho\n")
   (display "let's go\n"))
 @print{} hey ho
 @print{} let's go
@@ -87,7 +87,7 @@ One can also establish local syntactic bindings with @code{let-syntax}.
 Bind each @var{keyword} to its corresponding @var{transformer} while
 expanding @var{exp1} @var{exp2} @enddots{}.
 
-A @code{let-syntax} binding only exists at expansion-time. 
+A @code{let-syntax} binding only exists at expansion-time.
 
 @example
 (let-syntax ((unless
@@ -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 a string literal.  It will work at a REPL, but
+not in a file, as 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.38.1


[-- Attachment #1.1.3: 0002-Doc-clarification-on-regexes-and-encodings.patch --]
[-- Type: text/x-patch, Size: 1644 bytes --]

From f5140bf63c624b975f1dcf98dcf18bf7cc44abfa Mon Sep 17 00:00:00 2001
From: Jean Abou Samra <jean@abou-samra.fr>
Date: Sun, 11 Dec 2022 12:28:02 +0100
Subject: [PATCH 2/2] Doc: clarification on regexes and encodings

* doc/ref/api-regex.texi: make it more obviously clear that regexp
  matching supports only characters supported by the locale encoding.
---
 doc/ref/api-regex.texi | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/doc/ref/api-regex.texi b/doc/ref/api-regex.texi
index b14c2b39c..d778f969f 100644
--- a/doc/ref/api-regex.texi
+++ b/doc/ref/api-regex.texi
@@ -57,7 +57,11 @@ locale's encoding, and then passed to the C library's regular expression
 routines (@pxref{Regular Expressions,,, libc, The GNU C Library
 Reference Manual}).  The returned match structures always point to
 characters in the strings, not to individual bytes, even in the case of
-multi-byte encodings.
+multi-byte encodings.  This ensures that the match structures are
+correct when performing matching with characters that have a multi-byte
+representation in the locale encoding.  Note, however, that using
+characters which cannot be represented in the locale encoding can
+lead to surprising results.
 
 @deffn {Scheme Procedure} string-match pattern str [start]
 Compile the string @var{pattern} into a regular expression and compare
@@ -325,7 +329,7 @@ example the following is the date example from
 @code{string-match} call.
 
 @lisp
-(define date-regex 
+(define date-regex
    "([0-9][0-9][0-9][0-9])([0-9][0-9])([0-9][0-9])")
 (define s "Date 20020429 12am.")
 (regexp-substitute/global #f date-regex s
-- 
2.38.1


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 236 bytes --]