Suggested additional example to Emacs Lisp Manual: Variables: Let

Suggested additional example to Emacs Lisp Manual: Variables: Let

[ben rudgers]

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

I apologize for not entirely following the patch submission process. I'm
not sure I understand it fully yet.

The manual does not provide an example showing a locally scoped function.
Though the behavior can potentially be inferred from the documentation of
functions, an example showing the relationship between =let= and =funcall=
might be of practical help for someone who has not made a deep dive into
the manual.

I have appended the following to the documentation for =let= in the
attached file:

Functions defined within a @code{let} must be invoked using a call to
@code{funcall}.

@example
(defun foo (x)
  (let ((bar (lambda (y) (+ x y))))
    (funcall bar 3)))
(foo 4)
     @result{} 7
@end example

The standard internet search engines do not provide a well articulated
example at this time. Because locally scoped functions are a common idiom
in the Lisp family of languages, it seems likely that an example will be
helpful to programmers with experience in other Lisps. =let= seems like the
best place to put an example in the documentation.

Anyway, thanks for all you have done. If you have any questions or there is
anything I can do to help improve the documentation please let me know.

[-- Attachment #1.2: Type: text/html, Size: 1862 bytes --]

[-- Attachment #2: variables.texi --]
[-- Type: application/x-texinfo, Size: 93487 bytes --]

Re: Suggested additional example to Emacs Lisp Manual: Variables: Let

[John Wiegley]

>>>>> "br" == ben rudgers <ben.rudgers@gmail.com> writes:

br> The manual does not provide an example showing a locally scoped function.
br> Though the behavior can potentially be inferred from the documentation of
br> functions, an example showing the relationship between =let= and =funcall=
br> might be of practical help for someone who has not made a deep dive into
br> the manual.

I think it would be better to encourage the use of `cl-flet' or `cl-labels',
as though macros are specifically intended for binding local function
definitions, and will automatically handle whether the function should be a
`lambda' or a `closure', depending on the setting of `lexical-binding'.

Your approach may have merit in terms of pedagogy, but I'd prefer to nudge
users toward more idiomatic usage from the beginning.

@example
(require 'cl-macs)
(defun foo (x)
  (cl-flet ((bar (y) (+ x y)))
    (bar 3)))
(foo 4)
     @result{} 7
@end example

-- 
John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2

Re: Suggested additional example to Emacs Lisp Manual: Variables: Let

[ben rudgers]

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

Thanks John,

I don't disagree about the utility of cl-flet or cl-labels.

Because 'cl is documented in an independent document it is unclear to me
how that example would fit into the current editorial structure of the *GNU
Emacs Lisp Reference Manual*.

Obviously if 'cl-flet and 'cl-labels were merged into GNU Emacs Lisp, the
example would work to illustrate a method for writing a locally defined
functions. With the added benefit of avoiding the more cumbersome 'funcall
structure.

Ben




On Sun, Jan 29, 2017 at 1:20 PM, John Wiegley <jwiegley@gmail.com> wrote:

> >>>>> "br" == ben rudgers <ben.rudgers@gmail.com> writes:
>
> br> The manual does not provide an example showing a locally scoped
> function.
> br> Though the behavior can potentially be inferred from the documentation
> of
> br> functions, an example showing the relationship between =let= and
> =funcall=
> br> might be of practical help for someone who has not made a deep dive
> into
> br> the manual.
>
> I think it would be better to encourage the use of `cl-flet' or
> `cl-labels',
> as though macros are specifically intended for binding local function
> definitions, and will automatically handle whether the function should be a
> `lambda' or a `closure', depending on the setting of `lexical-binding'.
>
> Your approach may have merit in terms of pedagogy, but I'd prefer to nudge
> users toward more idiomatic usage from the beginning.
>
> @example
> (require 'cl-macs)
> (defun foo (x)
>   (cl-flet ((bar (y) (+ x y)))
>     (bar 3)))
> (foo 4)
>      @result{} 7
> @end example
>
> --
> John Wiegley                  GPG fingerprint = 4710 CF98 AF9B 327B B80F
> http://newartisans.com                          60E1 46C4 BD1A 7AC1 4BA2
>

[-- Attachment #2: Type: text/html, Size: 2570 bytes --]