doc: revamp explanation of implicit begin #4146
Conversation
Thanks to @rmculpepper for the initial improvement.
| @@ -64,6 +56,22 @@ positions, instead of forming an expression, the content of | |||
| This splicing behavior is mainly useful for macros, as we discuss | |||
| later in @secref["macros"]. | |||
|
|
|||
| The whole @racket[_body] sequence is sometimes said to have an @deftech{implicit begin}. | |||
There was a problem hiding this comment.
Why sometimes? Probably best to always or never (at least in the documentation we control).
There was a problem hiding this comment.
Also, I'm not sure it's clear that the metavariable body here refers to internal-definition contexts, so maybe The whole @racket[_body] sequence of an internal-definition context?
There was a problem hiding this comment.
One complication is that the Racket Guide doesn't really define what internal-definition context is, so I've been avoiding it. But perhaps we should define it, perhaps in the section "Internal Definitions".
| The whole @racket[_body] sequence is sometimes said to have an @deftech{implicit begin}. | ||
| The restriction of an @tech{implicit begin} follows the restriction of the @racket[_body] sequence: | ||
| the sequence should end with an expression. | ||
|
|
There was a problem hiding this comment.
An implicit begin is restricted in the same way as a @racket[_body]; it must end with an expression.
| @@ -194,10 +194,10 @@ equivalent to a @racket[define-values] form with a single @racket[_id]. | |||
|
|
|||
| When the grammar for a syntactic form specifies @racket[_body], then | |||
| the corresponding form can be either a definition or an expression. | |||
| A definition as a @racket[_body] is an @defterm{internal definition}. | |||
| A definition as a @racket[_body] is an @deftech{internal definition}. | |||
There was a problem hiding this comment.
Are you treating the metavariable body as the whole sequence? IIUC, elsewhere, the metavariable body is treated as a single form in the sequence (hence the usage of @racket[body]s in various places). So I think "a definition as a @racket[_body]" is correct already.
| @racket[begin] form is equivalent to splicing the @racket[form]s into | ||
| the enclosing context. | ||
| The @tech{internal-definition context} itself is said to have an | ||
| @deftech{implicit begin} of this first form. |
There was a problem hiding this comment.
"of the first form" is correct, but how about "The internal-definition context itself is treated as a begin containing definitions" or something more like that?
Thanks to @rmculpepper for the initial improvement.
I end up explaining it a bit differently in a way that I think flows a bit better. Let me know if there's any inaccuracy.
cc: @mflatt, @rmculpepper
Related to #2696