[PATCH] Possible Documentation Fix

[PATCH] Possible Documentation Fix

[Noah Lavine]

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

Hello all,

I was recently reading the syntax-case documentation (as part of my
project to make peg.scm use syntax-case), and I hit a paragraph that I
found difficult to understand. I think I figured out what it means.
The attached patch changes the paragraph to something that I think
would have been more clear to me on my first time reading it.

Could someone who understands syntax-case better than I do please
review it for correctness?

Thanks,
Noah

[-- Attachment #2: 0001-doc-ref-api-macros.texi-make-the-explanation-of-datu.patch --]
[-- Type: application/octet-stream, Size: 1378 bytes --]

From a93988c5f2f2138bd0765273aa7da6b9e567df59 Mon Sep 17 00:00:00 2001
From: Noah Lavine <nlavine@haverford.edu>
Date: Sat, 29 Jan 2011 13:04:55 -0500
Subject: [PATCH]  * doc/ref/api-macros.texi: make the explanation of datum->syntax in
     the syntax-case documentation a bit more clear.

---
 doc/ref/api-macros.texi |    9 ++++-----
 1 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index 1fbfa24..c96670c 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -574,11 +574,10 @@ Here's another solution that doesn't work:
              (if it then else)))))))
 @end example
 
-The reason that this one doesn't work is that there are really two environments
-at work here -- the environment of pattern variables, as bound by
-@code{syntax-case}, and the environment of lexical variables, as bound by normal
-Scheme. Here we need to introduce a piece of Scheme's environment into that of
-the syntax expander, and we can do so using @code{syntax-case} itself:
+The reason this doesn't work is that the binding of @code{'it} established in
+the outer let form is not substituted into the definition of @code{'it} in the
+inner let form, inside the @code{syntax} form. One way to make this
+substitution happen is to use @code{syntax-case} itself:
 
 @example
 ;; works, but is obtuse
-- 
1.7.3.5

Re: [PATCH] Possible Documentation Fix

[Andy Wingo]

Hi Noah,

Thanks for the review and patch!

On Sat 29 Jan 2011 19:08, Noah Lavine <noah.b.lavine@gmail.com> writes:

> Could someone who understands syntax-case better than I do please
> review it for correctness?

It is correct, but I kinda liked the explicit mention of pattern
variable environments in the original.  In syntax expansion, there are
lexical variables, bound in lexical environments, and pattern variables,
bound in syntax-expansion environments.  The confusion addressed by that
paragraph was to treat a lexical variable as a pattern variable.

Also:

> +The reason this doesn't work is that the binding of @code{'it} established in

No need to quote symbols that are in @code{}.

Do you still think the discussion of environments is distracting?
Documentation should ulitimately be for users, and if the original text
is not useful at all, by all means we should change it.

Andy
-- 
http://wingolog.org/

Re: [PATCH] Possible Documentation Fix

[Noah Lavine]

Hi,

> It is correct, but I kinda liked the explicit mention of pattern
> variable environments in the original.  In syntax expansion, there are
> lexical variables, bound in lexical environments, and pattern variables,
> bound in syntax-expansion environments.  The confusion addressed by that
> paragraph was to treat a lexical variable as a pattern variable.
...
> Do you still think the discussion of environments is distracting?
> Documentation should ulitimately be for users, and if the original text
> is not useful at all, by all means we should change it.

Not distracting, it's just that I didn't understand it immediately
because it didn't explicitly say that I was defining variables in two
different sorts of environments - just that there were two different
sorts of environments. How about this language?

The reason that this one doesn't work is that there are really two
environments at work here -- the environment of pattern variables, as
bound by @code{syntax-case}, and the environment of lexical variables,
as bound by normal Scheme. The outer let form establishes a binding in
the environment of lexical variables, but the inner let form is inside
a syntax form, where only pattern variables will be substituted. Here
we need to introduce a piece of the lexical environment into the
pattern variable environment, and we can do so using
@code{syntax-case} itself:

Noah

Re: [PATCH] Possible Documentation Fix

[Andy Wingo]

On Mon 31 Jan 2011 20:54, Noah Lavine <noah.b.lavine@gmail.com> writes:

> How about this language?

Looks great to me!  Would you mind submitting an updated patch?

Also, if you like, please add yourself to the Guile group on savannah.
Let Ludo and I know when/if you've done this and we'll be happy to add
you there.  Let's keep up the great discussion on the list, but it's
wonderfully convenient to be able to commit small patches like these
there.

Cheers,

Andy
-- 
http://wingolog.org/

Re: [PATCH] Possible Documentation Fix

[Noah Lavine]

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

Hi,

> Looks great to me!  Would you mind submitting an updated patch?

It's attached.

> Also, if you like, please add yourself to the Guile group on savannah.
> Let Ludo and I know when/if you've done this and we'll be happy to add
> you there.  Let's keep up the great discussion on the list, but it's
> wonderfully convenient to be able to commit small patches like these
> there.

Done.

Thanks,
Noah

[-- Attachment #2: 0001-doc-ref-api-macros.texi-make-the-difference-between-.patch --]
[-- Type: application/octet-stream, Size: 1660 bytes --]

From 7e0baaa41cd30bdf305da38a3aa9c59be80dfa66 Mon Sep 17 00:00:00 2001
From: Noah Lavine <nlavine@haverford.edu>
Date: Wed, 2 Feb 2011 09:52:10 -0500
Subject: [PATCH]  * doc/ref/api-macros.texi: make the difference between pattern variables
     and lexical variables a bit clearer.

---
 doc/ref/api-macros.texi |   13 ++++++++-----
 1 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index 1fbfa24..5f15fb7 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -574,11 +574,14 @@ Here's another solution that doesn't work:
              (if it then else)))))))
 @end example
 
-The reason that this one doesn't work is that there are really two environments
-at work here -- the environment of pattern variables, as bound by
-@code{syntax-case}, and the environment of lexical variables, as bound by normal
-Scheme. Here we need to introduce a piece of Scheme's environment into that of
-the syntax expander, and we can do so using @code{syntax-case} itself:
+The reason that this one doesn't work is that there are really two
+environments at work here -- the environment of pattern variables, as
+bound by @code{syntax-case}, and the environment of lexical variables,
+as bound by normal Scheme. The outer let form establishes a binding in
+the environment of lexical variables, but the inner let form is inside a
+syntax form, where only pattern variables will be substituted. Here we
+need to introduce a piece of the lexical environment into the pattern
+variable environment, and we can do so using @code{syntax-case} itself:
 
 @example
 ;; works, but is obtuse
-- 
1.7.4

Re: [PATCH] Possible Documentation Fix

[Andy Wingo]

On Wed 02 Feb 2011 15:53, Noah Lavine <noah.b.lavine@gmail.com> writes:

>> Looks great to me!  Would you mind submitting an updated patch?
>
> It's attached.

Thanks.  I added a summary line and committed it.

I've added you to the Guile group.  If you don't mind, please continue
to post patches to the list for a little while.  Try to rebase before
pushing patches to the Guile repo; merge commits are OK sometimes, but
we like having a nice linear history.

I guess in short the thing is to keep up the excellent patch-quality
that you already have!

Happy hacking,

Andy
-- 
http://wingolog.org/

Re: [PATCH] Possible Documentation Fix

[Noah Lavine]

> I've added you to the Guile group.  If you don't mind, please continue
> to post patches to the list for a little while.  Try to rebase before
> pushing patches to the Guile repo; merge commits are OK sometimes, but
> we like having a nice linear history.
>
> I guess in short the thing is to keep up the excellent patch-quality
> that you already have!

Will do, and thank you!

Noah