A community for the timeless and infinitely powerful editor. Want to see what Emacs is capable of?!
Everyone can contribute to the documentation to make it better. Consider doing so.
Remember, no one gets paid to maintain or document Emacs, so the quality of the documentation is really pretty remarkable for how good it is.
It can always be made better, though.
These days, prompting chat GPT is the way to go for generating small examples and asking about things with little background.
M-x elisp-index-search. The Elisp manual is not bad, almost pretty good. There's some examples in shortdocs, but I think shortdocs use case is dead because of generative AI's and will only get more dead.
Sometimes we write Elisp examples: https://github.com/positron-solutions/transient-showcase I have to update that because transient got some upgrades.
Use ielm and eval-last-sexp as well as eval-region.
Install the helpful package for useful commands like helpful-symbol.
I think once I got familiar with all of the various flavors of let binding and mapc and mapcar, even if what I was doing didn't seem like mind-blowing code, it also is pretty straightforward to read and write.
Now it should be pretty easy. You just need this configuration to avoid mispelling lambdas:
(defun pmx-greek-lambda ()
(font-lock-add-keywords
nil
`(("\\"
(0 (progn (compose-region (match-beginning 0) (match-end 0)
,(make-char 'greek-iso8859-7 107))
nil))))))
(add-hook 'emacs-lisp-mode-hook 'pmx-greek-lambda)
(add-hook 'inferior-emacs-lisp-mode-hook 'pmx-greek-lambda)Do you use org-edit-special in Org Mode (bound to C-c ' by default) to edit code blocks? It opens the code block in special temporary buffer with proper major mode enabled so you can edit the source code block with all the batteries included.
Agree with your sentiment about documentation. Some people have made great efforts to document, but since eMacs is so big you can’t document it all. The people that know about the things think some stuff is obvious.
The good thing is, it’s 2023 and we have AI. Ask chatgpt to write the code for you. It basically has access to every resource available and can help you if you’re stuck. I use it to write eMacs config stuff all the time.
It is becauses most people don't know LISP and overlook it's different paradigm
What makes learning Emacs and Elisp so hard? I think you've begged the question in the classic sense—your question contains the answer! The issue I think is that to really understand Emacs you have to understand Elisp and the Emacs environment.
If you focus only on one, it's hard to work with Emacs. Knowing Elisp without understanding how to work with hooks, and modes, and when (and whether) to work with the Custom system, and when configuration code should load before vs. after a package loads… well, you're not going to be able to do a whole lot with that Elisp! And Emacs knowledge without Elisp means you're going to know what you want to do and maybe even how to do it but you're going to have some fundamental misunderstandings of the code itself, leading to errors and bugs and a lot of frustration.
Thinking about this, I think the reason the documentation can be so challenging to figure out is that, as someone said further up there, this is all run by volunteer efforts, and, as such, they have to prioritize where their limited resources go. So the approach it seems to me that they've taken is to document as much of the Emacs environment as they can, but focus not on all of Elisp, but how it's different from other Lisps, and assume you can teach yourself Lisp.
I'm not really sure it's true that this was the purposeful prioritization from the documentation writers—there's a pretty extensive Elisp manual, and a nice Elisp tutorial in the manual (typically C-h i)—but it's not the level of resources nor the beginner-friendly approach that you see with learning a (somewhat) more practical Lisp, like Scheme or Racket or Common Lisp or Clojure. I don't mean to put words in the mouth of the tireless and selfless documentation writers, nor at all demean them! But either way, it's the same result from a learner's perspective.
So given the situation (as I see it), how do you learn Emacs? I highly recommend learning another Lisp, since there are more resources and tutorials on those than Elisp. Racket and Scheme.are IMO the easiest to get started with, and fun besides.
One final thought on learning Emacs: I think I stunted my growth for a while by using a framework on top of Emacs—I learned neither proper Elisp nor how Emacs worked. I learned a little about how my framework worked, and little about Emacs itself. I used Doom Emacs, but most frameworks have this issue. I've heard there are some frameworks that are better geared towards teaching you Emacs, so maybe this doesn't apply at all. But I think Doom Emacs is more geared to transitioning folks from Vim (which helped me, for sure!), and the framework they've built on top of it, while powerful, isn't, in my "n of 1" experience, good for learning.
Anyway, hope these thoughts help, and besides agreeing with folks that one of the best things you can do to learn and help others learn is to contribute to the documentation, this and the org-mode reddit are good places to ask clarifications—especially if it's clear it's a clarification and you've attempted your research first! (We're friendly, but we're friendlier if you demonstrate you're putting in the effort too.)
Cheers!
Thanks a lot for your response.
I will consider leaving prelude away, and dive into my own Emacs configuration. I am afraid of the time-consuming experience that it will be, but I hope it's worth it (and seeing the responses here, I definitely think it is).
Learning emacs via the emacs for scratch setup drive me into learning elisp. I'm no guru but it did set me up with a really solid foundation.
I think one has to be pragmatic, and only put effort to features that are actually useful. Don't put hours writing an elisp function which only saves you 10 seconds in a month. I'm saying this, because I had to stop myself from spending time on Emacs. I realized that my config is OK for me. I still have a lot of ideas how to make it better, but I simply don't do them, because it doesn't matter too much. Of course, I still do smaller tweaks, but otherwise I spend my time on more useful things. If someone had told me this before I started using emacs, they would have saved several days of not-too-useful emacs configuration for me. Of course, it was fun, I did it as a hobby, but still, it wasn't the smartest way to spend my free time.
But I struggle to achieve my learning of Elisp.
I think it is on your side. Sorry to tell it open, but Lisp(s) are very easy to learn and pick up. I don't know what you are teaching and what your expertize is in, but for me Lisp was as easy as VisualBasic.
The documentation is austere.
Emacs and Emacs Lisp are by fart the most documented Lisp applications. I can agree that it might be a bit outdated in terminology, and both terminology and API need some acclimatization since they predate the terminology we use today, and Lisp is a bit different from your ordinary Python/C/Java-like language. But I wouldn't say it is very hard; just different.
I found TODAY by CHANCE in this page
It has been in your Emacs all along, for a long time, since it is a part of Org manual that comes with your Emacs. You have to be more curious about what you are doing if you want to learn it and understand it. Nobody is going to throw knowledge at you; that happens only in classes. As a teacher, you should know that better than anyone else. If you want to learn and develop as Elisp programmer you will have to dig in yourself, be curious, search, read manual. Emacs Lisp is one of the most discoverable and documented Lisps and probably programming languages at all. You can C-h f to see docs directly in Emacs, and than just 's' in help window to see the source code. There are manuals for many parts of Emacs, including Org, that are built into your Emacs; you have debugging tools and lots of code to look at. You can also use Helpful which shows you the source code per default.
we don't have a smooth learning experience with Emacs
A learning experience is very subjective. It depends on many things. One of them is a person's ability as well as the will to learn.
Am I the only one to experience this ?
Probably not the only one, but also probably not the most representative example either. I am sorry. I am not trying to put you down as a person, but just suggesting that you should be more active, curious and looking for help yourself. As said, people can only provide you with manuals and material, but you have to look it up yourself, unless you can find an Emacs course. There are some online, perhaps that suits you better? Might be worth your time and small money investment. Perhaps look at some videos, or simply search for Elisp tutorials. There are some around.
It sounds like a good side project reach out to me to outline goals and objectives.
If I understand correctly, you are asking why is documentation using bad code examples that are not explanatory and/or usable?
If so, then I believe we can exonerate the emacs community from this issue as this is an industry-wide problem. I recall trying to figure out what a .NET class do from the generic unusable examples given in MS code, and more recently trying to divine meaning from the almost usable but never truly so code examples in Angular documentation. And you'll see that everywhere. I got used to ignore documentation and just read the code. Tests sometimes help as they are actual programs that use the stuff in question, but it does seem like writing good, usable documentation is an art form no one bothered to master. Or even apprentice in.
There's a reason to that, code examples are written by people who are experts in the technology they are documenting. They have no way of knowing what is needed for someone new to understand in order to use it, so they default on writing the most basic code example they can come up with. It's a known issue and you eventually learn to live with it.
Also, don't bother complaining. You are getting this great tool (either emacs or Org-Mode) free and due to the great effort of its writers and maintainers (and I am always amazed at the scope of things that were created this way, it's truly something to be proud of), so be thankful that it actually has documentation and besides, if you don't like something, fix it and send them the patch, don't complain! I mean, you won't get to write that patch because you can't understand the program due to its documentation, but hey, who said life is fair.
Also, don't bother complaining. You are getting this great tool (either emacs or Org-Mode) free and due to the great effort of its writers and maintainers (and I am always amazed at the scope of things that were created this way, it's truly something to be proud of), so be thankful that it actually has documentation and besides, if you don't like something, fix it and send them the patch, don't complain! I mean, you won't get to write that patch because you can't understand the program due to its documentation, but hey, who said life is fair.
I’m eternally in debt with people who made Emacs possible. Emacs taught me how to think, show me the «literate programming» that I love so much. This is why I’m currently frustrating.
But, you are totally right. Thanks for this important reminder that we have such a great tool for free, and with such freedom.
I'm aiming at both sides. I have used a library in work that had a utf8 issue, and started digging through the issues on GitHub, only to find that each such issue was flagged as "wont fix" and the reason was 'no activity on this issue for X amount of time". Which is a tactic I would get fired for had I tried it. I pointed this out and immediately got "we-hell, Pull Requests are welcome". Which is rather not helping. Also, turns out it's a matter with a dependency of that library, which you only found if you went through each issue. But then again, that guy was publishing that library out of the goodness of his heart, so you can only bitch up to a certain point. It's kinda odd because that bug caused me to waste a day and that meant I wasted my employer's money on the issue. So this "labour of love" and voluntary effort can cost people money due to the "I'm not getting paid to do this" attitude sometimes involved with the project. IT is a double edged sword.
I often thought that emacs should have a live repl game tutorial
like clojure koans but as an exploration of basic emacs abilities, then regular editing abilities, then fancier, then edebug and defmacro
If you have the right mindset learning Emacs can be way more enjoyable than learning any other tool.
It's just that the mindset required is the old school pre-Internet programmer mindset. You need to make a habbit of internalizing the documentation. When you're doing something, look into the appropriate section of the manual, to see if you really know all the manual has to say regarding the subject. You also need to track which portions of the manuals you've learned and which you haven't. Also, yes, learn to efficiently use info. It takes an hour, but would serve you well for years.
After you've established those habbits, you'd understand the superiority of the Emacs way, because you'd be learning topics in a systematic manner, instead of just learning a hodgepodge of random hacks from Stack Overflow, reddit and other sources.
Learn enough to figure out how to use "Use Package" and figure out what packages you like, and what you truly hate about Emacs so you can customize the fuck out of it and BTFO the shitty defaults.
Store your config in GitHub and use GNU Stow to deploy it on each of your machines.
Past that, the only truly fucking "hard" thing is LSP for Emacs for use within modern web dev settings.
The minute that someone makes a config that is as easy as an IDE for React and Typescript projects, then I am convinced Emacs is easy to use so I will agree with your frustration that it is pretty crazy that it has not kept up with other IDEs in this respect.
Otherwise, it's pretty good for Org mode and terminal. That is about all I use my actual old config for.
Spacemacs has gotten me closer to what I want though, but I just wish it was 100x easier with zero effort to get shit working like an IDE.
Maybe Doom is better though. Haven't touched that in ages either.
I found Babel/Org/Emacs wonderful, but what a pain in the ass to learn it !
These are four different things (along with Elisp), are you trying to learn them all together? This is a recipe for frustration and burnout. You can learn Emacs bottom up (starting with Elisp) or top down (Starting with Org, then Emacs). Pick an approach and stick to it.
The documentation is austere
This makes no sense -- Emacs' documentation is among the best for projects of its kind. The Emacs manual, Elisp manual, EINTR manual and Org manual have answered almost every question I've had, with very few exceptions.
So few examples are given.
The entirety of Emacs' source is open to you, and that's without including every package you have installed. Every usage of a macro or function is an example. xref-find-references is your friend.
There is too little blogs or books about Emacs, specifically about org and babel.
This may require a change in mindset. The reason I need books or blog posts to learn (say) Zig or Nix is because the manuals are out of date or publicly available source is unreadably dense. For the above given reasons, this is not true of Emacs.
The only time I've needed blog posts to learn about Emacs is for discovery -- bringing attention to the existence of a feature is something Emacs does struggle with, despite the introduction of new commands like shortdoc. Even then, I prefer to just look up the source or the manual to learn about a feature once I know it exists.
It's a game changer for a lot of my code, and would deserve a whole page to illustrate it. But no, it's given in a «niche» example.
*this* is only useful for post-processing babel blocks (as I understand it), and it is mentioned in the section on post-processing babel blocks. It is explained with examples too. I don't see where else it should go.
For such an old and wise piece of software, I can't understand why we don't have a smooth learning experience with Emacs.
Your idea of a smooth learning curve comes baked in with assumptions I don't share. The manuals can teach you everything you need to know to beat Emacs into the shape you want. I've had a much smoother time learning Emacs than I've had learning any other complex piece of software, like Bash, Systemd, Blender or (heaven forbid) Nix.
I have to say that I was a vim user for over 20 years - but this past January I moved to eMacs - simply because of Orgmode .
I have found better documentation and practicality in eMacs than I ever have in vim.
Also - I configured eMacs slowly - by hand - with no vim modes. I wanted to jump in feet first into the world of eMacs.
Your assessment of how difficult eMacs and elisp are to learn - has not been the case for me. But maybe I’m being more patient with the experience and enjoying the journey.
I can recommend the following resources: