Doc patches outstanding

Doc patches outstanding

[Jean Abou Samra]

[-- Attachment #1.1: Type: text/plain, Size: 528 bytes --]

Hi,

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

- Fix eval-when example.

   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=58646

- Clarify that regular expression matching is locale-dependent.

   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=57507

Thanks!

Jean


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

Re: Doc patches outstanding

[Dr. Arne Babenhauserheide]

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

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.

> - Fix eval-when example.
>
>   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=58646
>
> - Clarify that regular expression matching is locale-dependent.
>
>   https://debbugs.gnu.org/cgi/bugreport.cgi?bug=57507
>
> Thanks!

Thank you for your patches!

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: Doc patches outstanding

[Jean Abou Samra]

[-- 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 --]

Re: Doc patches outstanding

[Jean Abou Samra]

[-- Attachment #1.1: Type: text/plain, Size: 367 bytes --]

Le 11/12/2022 à 12:30, Jean Abou Samra a écrit :
> 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.


Friendly ping?

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

Re: Doc patches outstanding

[Dr. Arne Babenhauserheide]

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


Jean Abou Samra <jean@abou-samra.fr> writes:

> [[PGP Signed Part:No public key for A3F0F60B893397FE created at 2023-01-10T16:51:46+0100 using EDDSA]]
> Le 11/12/2022 à 12:30, Jean Abou Samra a écrit :
>> 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.
>
> Friendly ping?

Thank you! Got lost in panic about the village of Lützerath being
cleared to gather more coal than we can still burn without breaking the
Paris agreement …

I’ll try to apply them this evening.

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: Doc patches outstanding

[Dr. Arne Babenhauserheide]

[-- Attachment #1.1: Type: text/plain, Size: 1503 bytes --]

Hello Jean,

Jean Abou Samra <jean@abou-samra.fr> writes:
> Thank you for applying the first one nevertheless. I am attaching
> patch files for the other two, that should work better.

They are applied and pushed now — thank you, and thank you for your patience!

For the eval-when-example I wrote a small change to the wording, because
I found that the example actually runs in Guile 3.0.8, but retrieves the
runtime value of the date-time instead of the compile-time value.

Can you have a look? If it’s good to go from your side, I’d push it.

Subject: [PATCH] doc: More precise eval-when example description

* doc/ref/api-macros.texi: replace "will not work in a file" by "will
  cause problems in a file", because the example actually executes at
  runtime, so it works, but not as intended.
---
 doc/ref/api-macros.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index a353719cb..ea4e85d3f 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -1239,7 +1239,7 @@ the procedure should be made available at expansion-time.
 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:
+will cause problems in a file, as it cannot be byte-compiled:
 
 @example
 (use-modules (srfi srfi-19))


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.2: 0001-doc-More-precise-eval-when-example-description.patch --]
[-- Type: text/x-patch, Size: 1107 bytes --]

From 39fc107c76c48287b84abc2a51d6b3f778817560 Mon Sep 17 00:00:00 2001
From: Arne Babenhauserheide <arne_bab@web.de>
Date: Tue, 17 Jan 2023 07:17:56 +0100
Subject: [PATCH] doc: More precise eval-when example description

* doc/ref/api-macros.texi: replace "will not work in a file" by "will
  cause problems in a file", because the example actually executes at
  runtime, so it works, but not as intended.
---
 doc/ref/api-macros.texi | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index a353719cb..ea4e85d3f 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -1239,7 +1239,7 @@ the procedure should be made available at expansion-time.
 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:
+will cause problems in a file, as it cannot be byte-compiled:
 
 @example
 (use-modules (srfi srfi-19))
-- 
2.38.1


[-- Attachment #1.3: Type: text/plain, Size: 105 bytes --]



Best wishes,
Arne

-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]

Re: Doc patches outstanding

[Jean Abou Samra]

[-- Attachment #1.1: Type: text/plain, Size: 913 bytes --]



Le 17/01/2023 à 07:21, Dr. Arne Babenhauserheide a écrit :
> Hello Jean,
>
> Jean Abou Samra <jean@abou-samra.fr> writes:
>> Thank you for applying the first one nevertheless. I am attaching
>> patch files for the other two, that should work better.
> They are applied and pushed now — thank you, and thank you for your patience!
>
> For the eval-when-example I wrote a small change to the wording, because
> I found that the example actually runs in Guile 3.0.8, but retrieves the
> runtime value of the date-time instead of the compile-time value.
>
> Can you have a look? If it’s good to go from your side, I’d push it.


Well... you're right. Although it cannot be byte-compiled, it can be 
evaluated (actually, I find it surprising that evaluating a file 
evaluates the S-exprs one by one rather than first macroexpanding 
everything...).

You can push it.

Best,
Jean


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

Re: Doc patches outstanding

[Dr. Arne Babenhauserheide]

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


Jean Abou Samra <jean@abou-samra.fr> writes:

> Le 17/01/2023 à 07:21, Dr. Arne Babenhauserheide a écrit :
>> Jean Abou Samra <jean@abou-samra.fr> writes:
>>> Thank you for applying the first one nevertheless. I am attaching
>>> patch files for the other two, that should work better.
>> They are applied and pushed now — thank you, and thank you for your patience!
>>
>> For the eval-when-example I wrote a small change to the wording, because
>> I found that the example actually runs in Guile 3.0.8, but retrieves the
>> runtime value of the date-time instead of the compile-time value.
>>
>> Can you have a look? If it’s good to go from your side, I’d push it.
>
> Well... you're right. Although it cannot be byte-compiled, it can be
> evaluated (actually, I find it surprising that evaluating a file
> evaluates the S-exprs one by one rather than first macroexpanding
> everything...).

It’s pushed now — thank you for checking!

If you have more small changes you’d like to get merged, feel free to
ping me for review.

Might not be very fast, but I’m glad we’re moving forward on these.

Best wishes,
Arne
-- 
Unpolitisch sein
heißt politisch sein,
ohne es zu merken.
draketo.de

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 1125 bytes --]