Some ideas with Emacs

classic Classic list List threaded Threaded
114 messages Options
1234 ... 6
Reply | Threaded
Open this post in threaded view
|

Some ideas with Emacs

c4droid
Hi, I'm a user and a fanatical fans for Emacs. I'd like to share a few ideas for about Emacs Lisp.
Emacs Lisp is powerful, it's undeniable. But when I studied Emacs Lisp, I found that there were too few examples of function use in the tutorial. Also when using Emacs Lisp for Emacs plugin development and configuration, Sometimes you write your own plugins will affect the configuration you write, so I'd like to make a few ideas for Emacs Lisp:
First, suggest to add more examples of functions in the tutorial, most for Emacs Lisp Reference Manual, which can lower the learning threshold.
Second, in developing the Emacs plugins, create a virtual environment, like Python virtualenv, so that we can test the plugin in the virtual environment so that we do not need to affect the configuration outside the virtual environment. That's can implement plugin development environment and configuration isolation.
Although my suggestion may be a little trivial and even useless. But if my suggestions can help beginners like me go further, I think it's worth it.
Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Marcin Borkowski-3

On 2019-11-29, at 10:05, Anonymous <[hidden email]> wrote:

> Hi, I'm a user and a fanatical fans for Emacs. I'd like to share a few ideas for about Emacs Lisp.
> Emacs Lisp is powerful, it's undeniable.&nbsp;But when I studied Emacs Lisp, I found that there were too few examples of function use in the tutorial.&nbsp;Also when using Emacs Lisp for Emacs plugin development and configuration,&nbsp;Sometimes you write your own plugins will affect the configuration you write, so I'd like to make a few ideas for Emacs Lisp:
> First, suggest to add more examples of functions in the tutorial, most for Emacs Lisp Reference Manual, which can lower the learning threshold.

I had a plan to write an intermediate book on Elisp, but Real Life™
intervened.  I still have the stuff I managed to write, and if I live
long enough, I'm going to get back to this project (the current plan is
late 2020 - I'm finishing work on another book now, which is long
overdue, and I cannot postpone it more because it is a joint work with
two other people).  Would you be interested?  What would you like to see
in such a book?  (The idea was - and is - to start approximately where
Robert Chassell's "Elisp Intro" ends.)

> Second, in developing the Emacs plugins, create a virtual environment, like Python virtualenv, so that we can test the plugin in the virtual environment so that we do not need to affect the configuration outside the virtual environment. That's can implement plugin development environment and configuration isolation.
>
> Although my suggestion may be a little trivial and even useless.&nbsp;But if my suggestions can help beginners like me go further, I think it's worth it.

AFAIK, this is _far_ from trivial.  However, you can always start
a fresh Emacs instance with -Q.  For more advanced configs, you may
start a fresh Emacs instance with the config directory in /tmp or
whatever.  (Shameless plug: I blogged about it a few weeks ago, see
http://mbork.pl/2019-11-04_Starting_Emacs_with_custom_configuration_directory.)

Now that I think of it, we could even have an Emacs command to start
a fresh Emacs instance with a given file already loaded.  WDYT?

Hth,

--
Marcin Borkowski
http://mbork.pl

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Stefan Kangas
In reply to this post by c4droid
Anonymous <[hidden email]> writes:

> First, suggest to add more examples of functions in the tutorial,
> most for Emacs Lisp Reference Manual, which can lower the learning
> threshold.

I think this is a fine idea that would make the manual more useful.
But the elisp manual is also printed on paper, and is from what I
understand already very long.  Does it make sense to include examples
in the info manual only?

> Second, in developing the Emacs plugins, create a virtual
> environment, like Python virtualenv, so that we can test the plugin
> in the virtual environment so that we do not need to affect the
> configuration outside the virtual environment. That's can implement
> plugin development environment and configuration isolation.

I think what you would do is something like "emacs -Q -l myenv.el" and
then set up the load-path, requires, and whatever else you need in
myenv.el.

> Although my suggestion may be a little trivial and even useless. But
> if my suggestions can help beginners like me go further, I think
> it's worth it.

We very much need to get more people hacking on Emacs.  So any
suggestion which could help us achieve that is welcome, I think.

Best regards,
Stefan Kangas

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

c4droid
In reply to this post by Marcin Borkowski-3
I'm interested your book, I'm waiting for a professional book talk about Emacs Lisp and Emacs plugins development.
For environment isolation, maybe put plugin source at /tmp and call emacs with -Q option is best practices. In my mind, I think the plugin develop workflow is:
Real environment:
Write, Modify code
Virtual environment:
Run, test, debug plugin, when debug, real environment using emacs lisp debugger attach virtual environment for debug.


---Original---
From: "Marcin Borkowski"<[hidden email]>
Date: Fri, Nov 29, 2019 19:16 PM
To: "Anonymous"<[hidden email]>;
Cc: "emacs-devel"<[hidden email]>;
Subject: Re: Some ideas with Emacs


On 2019-11-29, at 10:05, Anonymous <[hidden email]> wrote:

> Hi, I'm a user and a fanatical fans for Emacs. I'd like to share a few ideas for about Emacs Lisp.
> Emacs Lisp is powerful, it's undeniable.&nbsp;But when I studied Emacs Lisp, I found that there were too few examples of function use in the tutorial.&nbsp;Also when using Emacs Lisp for Emacs plugin development and configuration,&nbsp;Sometimes you write your own plugins will affect the configuration you write, so I'd like to make a few ideas for Emacs Lisp:
> First, suggest to add more examples of functions in the tutorial, most for Emacs Lisp Reference Manual, which can lower the learning threshold.

I had a plan to write an intermediate book on Elisp, but Real Life™
intervened.  I still have the stuff I managed to write, and if I live
long enough, I'm going to get back to this project (the current plan is
late 2020 - I'm finishing work on another book now, which is long
overdue, and I cannot postpone it more because it is a joint work with
two other people).  Would you be interested?  What would you like to see
in such a book?  (The idea was - and is - to start approximately where
Robert Chassell's "Elisp Intro" ends.)

> Second, in developing the Emacs plugins, create a virtual environment, like Python virtualenv, so that we can test the plugin in the virtual environment so that we do not need to affect the configuration outside the virtual environment. That's can implement plugin development environment and configuration isolation.
>
> Although my suggestion may be a little trivial and even useless.&nbsp;But if my suggestions can help beginners like me go further, I think it's worth it.

AFAIK, this is _far_ from trivial.  However, you can always start
a fresh Emacs instance with -Q.  For more advanced configs, you may
start a fresh Emacs instance with the config directory in /tmp or
whatever.  (Shameless plug: I blogged about it a few weeks ago, see
http://mbork.pl/2019-11-04_Starting_Emacs_with_custom_configuration_directory.)

Now that I think of it, we could even have an Emacs command to start
a fresh Emacs instance with a given file already loaded.  WDYT?

Hth,

--
Marcin Borkowski
http://mbork.pl
i
Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

c4droid
In reply to this post by Stefan Kangas
I mean, include one or two examples for tell reader the describe function how to use, that's enough.
Call emacs with -Q -l option to load plugin development options file, it's also a solution. Suppose I have configured the development environment, but do not have to have the configuration to start, without code completion, have a little uncomfortable for me. :)


---Original---
From: "Stefan Kangas"<[hidden email]>
Date: Fri, Nov 29, 2019 19:37 PM
To: "Anonymous"<[hidden email]>;
Cc: "emacs-devel"<[hidden email]>;
Subject: Re: Some ideas with Emacs

Anonymous <[hidden email]> writes:

> First, suggest to add more examples of functions in the tutorial,
> most for Emacs Lisp Reference Manual, which can lower the learning
> threshold.

I think this is a fine idea that would make the manual more useful.
But the elisp manual is also printed on paper, and is from what I
understand already very long.  Does it make sense to include examples
in the info manual only?

> Second, in developing the Emacs plugins, create a virtual
> environment, like Python virtualenv, so that we can test the plugin
> in the virtual environment so that we do not need to affect the
> configuration outside the virtual environment. That's can implement
> plugin development environment and configuration isolation.

I think what you would do is something like "emacs -Q -l myenv.el" and
then set up the load-path, requires, and whatever else you need in
myenv.el.

> Although my suggestion may be a little trivial and even useless. But
> if my suggestions can help beginners like me go further, I think
> it's worth it.

We very much need to get more people hacking on Emacs.  So any
suggestion which could help us achieve that is welcome, I think.

Best regards,
Stefan Kangas
Reply | Threaded
Open this post in threaded view
|

Emacs: the Editor for the Next Forty Years (was Re: Some ideas with Emacs)

Juanma Barranquero
In reply to this post by Stefan Kangas

On Fri, Nov 29, 2019 at 1:04 PM Stefan Kangas <[hidden email]> wrote:

> We very much need to get more people hacking on Emacs. 

With reminds me...

Did someone hear (or attend to) Perry E. Metzger's talk in this years' EmacsConf?

https://media.emacsconf.org/2019/26.html  

And if so, does anyone have any opinion about it?
Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Eli Zaretskii
In reply to this post by Stefan Kangas
> From: Stefan Kangas <[hidden email]>
> Date: Fri, 29 Nov 2019 12:37:31 +0100
> Cc: emacs-devel <[hidden email]>
>
> Anonymous <[hidden email]> writes:
>
> > First, suggest to add more examples of functions in the tutorial,
> > most for Emacs Lisp Reference Manual, which can lower the learning
> > threshold.
>
> I think this is a fine idea that would make the manual more useful.
> But the elisp manual is also printed on paper, and is from what I
> understand already very long.  Does it make sense to include examples
> in the info manual only?

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.

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Stefan Kangas
Eli Zaretskii <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Eduardo Ochs-2
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 <[hidden email]> wrote:
Eli Zaretskii <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Eli Zaretskii
In reply to this post by Stefan Kangas
> From: Stefan Kangas <[hidden email]>
> Date: Fri, 29 Nov 2019 14:34:44 +0100
> Cc: Anonymous <[hidden email]>, Emacs developers <[hidden email]>
>
> Eli Zaretskii <[hidden email]> 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 was talking about a tutorial, not about examples.

We already have examples in the ELisp manual, although it isn't
feasible to have an example for each possible use case.  We could add
more examples where the description is not self-explanatory enough,
but adding too much of them would be infeasible, I think, due to size
considerations.  We will have to consider that on a case by case
basis.

> 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.

A better strategy is to search the Emacs tree, IME.

> 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).

We already have examples where we think it's useful.

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

c4droid
Agree.


---Original---
From: "Eli Zaretskii"<[hidden email]>
Date: Fri, Nov 29, 2019 22:14 PM
To: "Stefan Kangas"<[hidden email]>;
Cc: "c4droid"<[hidden email]>;"emacs-devel"<[hidden email]>;
Subject: Re: Some ideas with Emacs

> From: Stefan Kangas <[hidden email]>
> Date: Fri, 29 Nov 2019 14:34:44 +0100
> Cc: Anonymous <[hidden email]>, Emacs developers <[hidden email]>
>
> Eli Zaretskii <[hidden email]> 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 was talking about a tutorial, not about examples.

We already have examples in the ELisp manual, although it isn't
feasible to have an example for each possible use case.  We could add
more examples where the description is not self-explanatory enough,
but adding too much of them would be infeasible, I think, due to size
considerations.  We will have to consider that on a case by case
basis.

> 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.

A better strategy is to search the Emacs tree, IME.

> 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).

We already have examples where we think it's useful.
Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Stefan Monnier
In reply to this post by Stefan Kangas
> I fail to see why a reference manual can't also include examples.

I don't think anyone would suggest that examples don't belong there.
Manpages are typical "reference manuals" and many of them
include(d) examples.

AFACT, currently we have some examples in the Elisp manual and very
few examples in docstrings.
It might be a good idea to encourage the addition of examples either in
docstrings or in the Elisp manual (or both).


        Stefan


Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Stefan Monnier
In reply to this post by Stefan Kangas
>> Second, in developing the Emacs plugins, create a virtual
>> environment, like Python virtualenv, so that we can test the plugin
>> in the virtual environment so that we do not need to affect the
>> configuration outside the virtual environment. That's can implement
>> plugin development environment and configuration isolation.
> I think what you would do is something like "emacs -Q -l myenv.el" and
> then set up the load-path, requires, and whatever else you need in
> myenv.el.

Indeed, currently the only way to do that is by using a separate
Emacs session.  Cask is a tool to automate this.  For some use cases
this is exactly what we need (e.g. testing a package on various
versions of Emacs), but in other use cases it's a pain to have to use
two separate Emacs sessions.

There's definitely room for improvement in this arena.

Juanma adds:
> With reminds me...
> Did someone hear (or attend to) Perry E. Metzger's talk in this years'
> EmacsConf?
> https://media.emacsconf.org/2019/26.html
> And if so, does anyone have any opinion about it?

I presume you're talking about the part where he discusses the future of
Emacs's extension language.  I do have some opinion about that, yes ;-)


        Stefan


Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Robert Pluim
>>>>> On Fri, 29 Nov 2019 10:43:19 -0500, Stefan Monnier <[hidden email]> said:
    Stefan> Juanma adds:
    >> With reminds me...
    >> Did someone hear (or attend to) Perry E. Metzger's talk in this years'
    >> EmacsConf?
    >> https://media.emacsconf.org/2019/26.html
    >> And if so, does anyone have any opinion about it?

    Stefan> I presume you're talking about the part where he discusses the future of
    Stefan> Emacs's extension language.  I do have some opinion about that, yes ;-)

Emacs already has two extension languages, three if you count
'C'. What benefits would another one offer?

Robert

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Michael Albinus
In reply to this post by Stefan Monnier
Stefan Monnier <[hidden email]> writes:

> AFACT, currently we have some examples in the Elisp manual and very
> few examples in docstrings.
> It might be a good idea to encourage the addition of examples either in
> docstrings or in the Elisp manual (or both).

Personally, I don't like docstring to be too verbose. Usually, when a
function is documented with both docstrings and a manual, I prefer to
put the examples in the manual.

But that's my taste, and maybe not the best approach. Don't know.

>         Stefan

Best regards, Michael.

Reply | Threaded
Open this post in threaded view
|

Adding examples in the doc (was: Some ideas with Emacs)

Stefan Monnier
>> AFACT, currently we have some examples in the Elisp manual and very
>> few examples in docstrings.
>> It might be a good idea to encourage the addition of examples either in
>> docstrings or in the Elisp manual (or both).
> Personally, I don't like docstring to be too verbose.

I tend to agree.  Of course part of it is that a verbose docstring is an
indication that the function is complex to use, but there's also simply
the impact on the visual distance between the function header and the code.

Another issue w.r.t examples is that editing Elisp code within
docstrings is a PITA (you don't get the usual
completion/indentation/... plus you have to be careful with escaping
' and friends so they don't get "shaped").

Also, docstrings have no formal structure and usually contain text, so
if we want to add examples in docstrings, I would prefer we first design
a structure to clearly distinguish text from code so we can render it
more elegantly.

Maybe examples should simply live *outside* of the function definition,
e.g. with

    (defexamples ...)

This might also have the benefit of being able to associate an example
with several functions (when the example shows how to combine calls to
various functions to get a particular result).

> Usually, when a function is documented with both docstrings and
> a manual, I prefer to put the examples in the manual.

I find code in texi files to be less convenient to edit/use.


        Stefan


Reply | Threaded
Open this post in threaded view
|

Re: Adding examples in the doc (was: Some ideas with Emacs)

Fu Yuan

AFACT, currently we have some examples in the Elisp manual and very
few examples in docstrings.
It might be a good idea to encourage the addition of examples either in
docstrings or in the Elisp manual (or both).
Personally, I don't like docstring to be too verbose.

I tend to agree.  Of course part of it is that a verbose docstring is an
indication that the function is complex to use, but there's also simply
the impact on the visual distance between the function header and the code.

FYI there is a package that does similar things: https://github.com/xuchunyang/elisp-demos

Yuan
Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Eli Zaretskii
In reply to this post by Michael Albinus
> From: Michael Albinus <[hidden email]>
> Cc: Stefan Kangas <[hidden email]>,  Eli Zaretskii <[hidden email]>,
>   Anonymous <[hidden email]>,  Emacs developers <[hidden email]>
> Date: Fri, 29 Nov 2019 19:58:21 +0100
>
> Stefan Monnier <[hidden email]> writes:
>
> > AFACT, currently we have some examples in the Elisp manual and very
> > few examples in docstrings.
> > It might be a good idea to encourage the addition of examples either in
> > docstrings or in the Elisp manual (or both).
>
> Personally, I don't like docstring to be too verbose. Usually, when a
> function is documented with both docstrings and a manual, I prefer to
> put the examples in the manual.

I agree: the examples should be mostly in the manual.  Doc strings
should only have examples if it is otherwise very hard to explain
something.

Reply | Threaded
Open this post in threaded view
|

Re: Adding examples in the doc

Michael Albinus
In reply to this post by Stefan Monnier
Stefan Monnier <[hidden email]> writes:

>> Usually, when a function is documented with both docstrings and
>> a manual, I prefer to put the examples in the manual.
>
> I find code in texi files to be less convenient to edit/use.

I always prepare the example in *scratch*. Copied to the texi file only
when it works.

>         Stefan

Best regards, Michael.

Reply | Threaded
Open this post in threaded view
|

Re: Some ideas with Emacs

Michael Albinus
In reply to this post by Eli Zaretskii
Eli Zaretskii <[hidden email]> writes:

>> > AFACT, currently we have some examples in the Elisp manual and very
>> > few examples in docstrings.
>> > It might be a good idea to encourage the addition of examples either in
>> > docstrings or in the Elisp manual (or both).
>>
>> Personally, I don't like docstring to be too verbose. Usually, when a
>> function is documented with both docstrings and a manual, I prefer to
>> put the examples in the manual.
>
> I agree: the examples should be mostly in the manual.  Doc strings
> should only have examples if it is otherwise very hard to explain
> something.

Shall we say something like this in "(elisp) Documentation Tips"?

Best regards, Michael.

1234 ... 6