> From: Stefan Kangas <stefan@marxist.se> > Date: Fri, 29 Nov 2019 14:34:44 +0100 > Cc: Anonymous <c4droid@foxmail.com>, Emacs developers <emacs-devel@gnu.org> > > 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 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.