Hi Anonymous and other people,

most people test small snippets of elisp code by executing sexps with
`C-x C-e' or variants of it, not by loading elisp files. My
(admittedly biased!) feeling is that the best way to help beginners
learn Lisp is by giving them sexps to play with - configurations,
plugins, and even long texts in English, are secondary...

I tried to do something in this direction in a package that I wrote
called "eev" that I often use to teach Emacs and programming to total
beginners - here are some links to it:

  http://angg.twu.net/#eev
  http://angg.twu.net/emacsconf2019.html
  http://elpa.gnu.org/packages/eev.html

It comes with lots of tutorials. If you run

  (find-eev-quick-intro)
  (find-eev-intro)
  (find-eval-intro)

these sexps will open three of its "sandboxed tutorials" in temporary
read-write buffers; I use read-write buffers to let users play with
the sexps in them more easily. Here are links to the htmlized versions
of these three tutorials:

  http://angg.twu.net/eev-intros/find-eev-quick-intro.html
  http://angg.twu.net/eev-intros/find-eev-intro.html
  http://angg.twu.net/eev-intros/find-eval-intro.html

The tutorial in (find-eval-intro) is one of the ones that is still
very messy and in need of being rewritten, but there are is a section
in it I think that is relevant to this discussion. You can access it
with:

  http://angg.twu.net/eev-intros/find-eval-intro.html#10
  (find-eval-intro "10. More on functions")

but let me copy it here...



  10. More on functions
  =====================
  A symbol - for example `f' - can be both a varible and a
  function; its "value as a variable" and its "value as a
  function" are stored in different places. Try:

    (setq f 2)
    (setq f 5)
    (defun f (x) (* x x))
    (defun f (x) (* 10 x))
    (symbol-value    'f)
    (symbol-function 'f)

  This is explained here:

    (find-elnode "Symbol Components")
    (find-elnode "Symbol Components" "value cell")
    (find-elnode "Symbol Components" "function cell")

  The content of a "function cell" is _usually_ a lambda
  expression. See:

    (find-elnode "Lambda Expressions")
    (find-elnode "What Is a Function")
    (find-elnode "What Is a Function" "lambda expression")
    (find-elnode "What Is a Function" "byte-code function")

  Try:

    (setq f 2)
    (setq f 5)
    (set 'f 2)
    (set 'f 5)
    (fset 'f (lambda (x) (* x x)))
    (fset 'f (lambda (x) (* 10 x)))
    (defun f (x) (* 10 x))
    (defun f (x) (* x x))
    (symbol-value    'f)
    (symbol-function 'f)
    (f 4)
    (f f)

    ((lambda (x) (* x x))
     4)
    ((lambda (x) (* 10 x))
     4)


I have only used that particular section in a couple of workshops -
i.e., in situations where the participants could easily try things,
discuss with their neighbors, and ask questions - but the point is
that I feel that we need more material like this... and I would love
to work with other people to produce it.

  Cheers,
    Eduardo Ochs
    http://angg.twu.net/#eev


On Fri, 29 Nov 2019 at 10:44, Stefan Kangas <stefan@marxist.se> wrote:

> Eli Zaretskii <eliz@gnu.org> writes:
>
> > I think if we want to have an ELisp tutorial, it should be a separate
> > manual.  The current ELisp manual is a reference manual, and written
> > as such.
>
> I fail to see why a reference manual can't also include examples.
> I've had to search the web to understand how to use things before,
> even after having carefully read the relevant parts of the elisp
> manual and the doc string.  An example says a thousand words, as the
> saying goes...
>
> I think the Python documentation is very good in this regard.  Here is
> one example:
>
> https://docs.python.org/3/library/stdtypes.html#mapping-types-dict
>
> To be clear, I'm not suggesting that we should mandate that we should
> include examples.  But I'd suggest to optionally add them where it
> makes sense, and possibly then only in the info version of the manual
> (since we lack space in the print edition).
>
> Best regards,
> Stefan Kangas
>
>