This is great. I have been dabbling in elisp myself (trying to debug a major mode I modified) and it is a nightmare, partially do to the lack of resources. The more resources the better.
While more resources surely are better, was there anything in particular you found lacking from the GNU documentation on Emacs Lisp? The reference manual or tutorial?
What lack of resources? Every symbol in Emacs is documented in detail via describe-function or describe-variable. Emacs ships with four entire books; "Emacs", "Emacs FAQ", "Emacs Lisp Intro", and "Elisp". "Emacs" documents pretty much every user-visible feature in Emacs, and "Elisp" documents every programmer-visible feature. (And yes, they are built in; try 'M-: (info "Elisp")'.
And if that's not enough, it comes with nearly a million lines of example code, that you can get at with three keystrokes; describe-function / describe-key (etc.), TAB (to select the link to the source code), ENT (to follow the link). From there, you can edit the code, press C-M-x, and immediately play with your changes. Emacs is written in Emacs Lisp, and you can view the code and edit it at runtime. This makes Emacs Lisp significantly easier to learn than pretty much anything else, where all you have books with snippets of code that nobody ever used or ever will use.
Emacs does not lack resources for learning Emacs Lisp.
Emacs has plenty of resources if you know Lisp - if you don't all it has is the reference manuals. I learnt to programme from IBM 360 Systems Manuals, and guess what, learning from reference manuals was shite then and is shite now.
I want to write a book that will get you to where you can profitably read the manuals.
Nah, the elisp intro is quite conversational and starts with "this is a list". The "Elisp" info page is a bit of a reference manual, but it is all well-organized and readable cover-to-cover. I learned Emacs Lisp this way and have a couple of the more popular Elisp projects on github, so the manual must have done something right :)
It might be a font issue. We are finalising some layout features at Hypernumbers - this side project website is layout in a spreadsheet (I know, I know) so there are going to be some glitches. I suspect it is might be font related.
Don't forget that since you can safely assume somebody learning emacs lisp is using emacs. You could provide some text as a commented emacs lisp buffer that can be evaluated in place, like a variant of literate programming.
One of the problems that I am trying to solve is 'finding the information' so using a traditional HTML/PDF documentation generating package (Sphinx from Python Docs) is the way I decided to go. That is why there is a big focus on 'key words in URL's' and link-juice and so on and so forth...
I also need to write a set of documentation for another project that couldn't be evaluated in place as a commented lisp buffer and this is kind of a practice for that, so...
And, Emacs comes with documentation on both Elisp and every built-in feature of Emacs itself... but apparently nobody reads that. It really confuses me, as the built-in documentation is like the whole point of Emacs...
No kidding! I've led a couple sessions where I've taught other developers how to use Emacs (basic or advanced usage), and I continually emphasize that the built-in help system (including info) is very good. You just have to get comfortable with the idiosyncratic terminology, and you can pick up half of that just from the C-h t tutorial.
Press C-h C-h (or type M-x help) and look at the menu that comes up. These are the essential ones, IMHO (I cut out about half):
You have typed M-x h e l p, the help character. Type a Help option:
(Use SPC or DEL to scroll through this text. Type q to exit the Help command.)
a command-apropos. Give a substring, and see a list of commands
(functions interactively callable) that contain
that substring. See also the apropos command.
f describe-function. Type a function name and get documentation of it.
i info. The info documentation reader.
k describe-key. Type a command key sequence;
it displays the full documentation.
m describe-mode. Print documentation of current minor modes,
and the current major mode, including their special commands.
t help-with-tutorial. Select the Emacs learn-by-doing tutorial.
v describe-variable. Type name of a variable;
it displays the variable's documentation and value.
w where-is. Type command name; it prints which keystrokes
invoke that command.
For example, type C-h a (command-apropos) and then type "compile". That brings up a list of commands with "compile" in their name. Each is also a hyperlink; moving the cursor to them and pressing Enter brings you to their documentation, which also usually includes a link to their definition in elisp.
"apropos" is a good example of using an idiosyncratic term used by the help system. Also: kill-ring, "window" vs. "frame", "point". You just need to learn these, but you can pick them up from the tutorial and Emacs docs in the info pages. (Most of the terms come out of old Lisp culture, AFAICT.)
also Emacs has a build-in (as of Emacs 24) mode which exports to pdf and html, and allows code snippets to be evaluated /in-situ/ -- see http://orgmode.org
Honestly, the frequent "answerers" on SO don't know their arse from their elbow either. The way to learn Lisp is reading the Emacs source code. When you wonder how something words, do a describe-key and follow the link to the code. Explore. Edit. Learn.
I'm mostly a vim user, but everytime I dabble in emacs (usually to play with org-mode :-)), it seems to have just about everything covered... Just curious.
36 comments
[ 2.9 ms ] story [ 86.6 ms ] threadAnd if that's not enough, it comes with nearly a million lines of example code, that you can get at with three keystrokes; describe-function / describe-key (etc.), TAB (to select the link to the source code), ENT (to follow the link). From there, you can edit the code, press C-M-x, and immediately play with your changes. Emacs is written in Emacs Lisp, and you can view the code and edit it at runtime. This makes Emacs Lisp significantly easier to learn than pretty much anything else, where all you have books with snippets of code that nobody ever used or ever will use.
Emacs does not lack resources for learning Emacs Lisp.
I want to write a book that will get you to where you can profitably read the manuals.
If that is really the end, it could use some padding.
Waiting for a rainy evening with nothing on the telly :(
The book will be fixed, the submission not so...
The scrollbars disappear if you remove this attribute:
.hn-wc-body { overflow: auto; }
It does not look like that for me on Firefox on Linux. The author probably just missed it because of different font availability/preferences.
On windows with Firefox 3.6.13 I get: http://imgur.com/G4yl8
On Linux with Firefox 3.6.13 I get: http://imgur.com/x5WRt
It might be a font issue. We are finalising some layout features at Hypernumbers - this side project website is layout in a spreadsheet (I know, I know) so there are going to be some glitches. I suspect it is might be font related.
I also need to write a set of documentation for another project that couldn't be evaluated in place as a commented lisp buffer and this is kind of a practice for that, so...
I can open it but I don't know how the navigation works.
"apropos" is a good example of using an idiosyncratic term used by the help system. Also: kill-ring, "window" vs. "frame", "point". You just need to learn these, but you can pick them up from the tutorial and Emacs docs in the info pages. (Most of the terms come out of old Lisp culture, AFAICT.)
Clever.
On a related note, here is an interesting article from Steve Yegge on elisp (useful for folks like me who just want a quick primer)
http://steve-yegge.blogspot.com/2008/01/emergency-elisp.html
I'm mostly a vim user, but everytime I dabble in emacs (usually to play with org-mode :-)), it seems to have just about everything covered... Just curious.