18

I use Emacs everyday as it is the standard editor for Erlang.

I decided as my New Years Resolution to learn to programme eLisp. I decided that writing a book about eLisp was the best way to learn.

I have make pretty good progress: Learn eLisp For Emacs

The strategic structure of the book is

  • getting started/basics
  • more advanced eLisp
  • writing a minor mode
  • writing a major mode

I have got through the basics (ie the first of these 4 points), covering:

  • evaluating expressions
  • debugging
  • adding menu items/toolbars
  • loading your own emacs files
  • etc, etc

If you are writing a book about a programming language you usually start by knowing the language well - well I don't - so my major problem now is a completeness problem:

  • How do I know that I have covered all the features that an Emacs programmer should have mastered?
  • How do I ensure that there aren't gaps in the content?

So I thought I would address these by asking the community here. My question is What Is Missing From My Table Of Contents? (in particular what should the more advanced eLisp Section contain).

Gordon Guthrie
  • 6,252
  • 2
  • 27
  • 52
  • 2
    Lovely intro for a book on Emacs, you hate it and you appear to think you can only learn it by sitting at the feet of a master. I'd seriously consider rethinking your preamble sir. – ocodo Feb 01 '11 at 23:25
  • 1
    I think you ought to add a pretty prominent disclaimer to that site to make the "I am writing this book to lean eLisp myself" part un-missable, and to ensure that people will know to check the definitive sources if they have any problems. – phils Feb 02 '11 at 01:26
  • 1
    I have to agree with Slomojo. It seems rather perverse to choose (volunteering, even!) to teach others how to do something you dislike and profess not to be very good at yourself. – Tyler Feb 03 '11 at 20:42
  • 1
    I don't dislike programming, indeed I am very good at it. There are some things I do and love (like Erlang) and there are somethings I do and dislike (like Linux/Unix and Emacs). In order to do Erlang better I need to use Emacs better. One of the things I most dislike about Emacs is the lack of beginners materials and a sort 'real programmers figure it out from the reference manuals' attitude that seems to exist around it. I learned programming from a shelf of IBM OS/360 manuals (3 feet long!) - but there is no excuse these days for that sort of stuff. – Gordon Guthrie Feb 04 '11 at 14:05
  • 'Programme'? http://www.dailywritingtips.com/get-with-the-programme/ – ealfonso Oct 14 '13 at 02:41

4 Answers4

14

Now that's an interesting way to learn a language...

I think you've probably skipped a bunch of the fundamentals in the getting started/basics section. If you've not already read it, I recommend reading "An Introduction To Programming In Emacs Lisp" (at gnu.org), which covers what I'd expect to see in the "basics" portion. I won't bother cut/paste the table of contents.

As far as knowing when you've written a complete book... Well, once you've re-written the Emacs Lisp manual in "how to" form, you know you're done. Alternatively, if you've written a book that can be used to answer/interpret all of the elisp and emacs questions, then you've probably got decent coverage.

What advanced features could you write about? There's advice, process communication, non-ASCII text, syntax tables, abbrevs, text properties, byte compilation, display tables, images, and a bunch more in the manual.

Note: The proper capitalization of elisp is either all lowercase, or possibly an uppercase E. The GNU documentation doesn't use "elisp" very much at all (mostly as a directory name, all lowercase), it prefers "Emacs Lisp."

Note: In the current version of your book, you treat global variables negatively. It's probably worth reading the RMS paper to gain some insight into the design decisions made, specifically on global variables as well as dynamic binding (the latter which you've yet to cover, which is a key (basic) concept which you've already gotten wrong in your book).

Community
  • 1
  • 1
Trey Jackson
  • 73,529
  • 11
  • 197
  • 229
  • I have read both the GNU manuals - but they are not so much use if you don't know Lisp/elisp. The focus in my book is 'always working code'. Read, try, get something working'.The whole binding issue is my biggest concern. A couple of people on the mailing list said "Hey use the CL package to make it like common Lisp" but that wasn't so much help. In what way have I got it wrong so far in the book? – Gordon Guthrie Feb 02 '11 at 07:50
  • I am really trying to understand which advanced features are necessary to get a user comfortable with writing code in elisp - such that they can 'self-server' from the existing (comprehensive) documentation. – Gordon Guthrie Feb 02 '11 at 07:58
  • I treat global variables negatively because in 1984 I used a common data structure in the 22nd line of a Fortran programme and in 1986 I spent 8 months looking for the bug (full time - 8 months, 1 bug). I now programme in Erlang which eschews global variables/shared state - indeed it doesn't even let variables vary! – Gordon Guthrie Feb 02 '11 at 08:00
  • @Gordon Regarding what you've gotten wrong. `set` and `setq` do not define global variables, the description of symbols is not accurate, the book often conflates returning values with side-effects (messages), the discussion of the scope of fill-column is not accurate, etc. – Trey Jackson Feb 02 '11 at 17:55
  • Cheers Trey, will review what I have written so far with those comments in mind. – Gordon Guthrie Feb 02 '11 at 19:23
4

Instead of asking the community here, why not use what the community already offers? Review all the questions tagged "elisp" and see where they fit it your book. A survey of what people actually want to understand could be some of the best information you will get.

Dingo
  • 3,305
  • 18
  • 14
4

"I have read both the GNU manuals - but they are not so much use if you don't know Lisp/elisp."

Tip: Emacs is not much use if you don't know Lisp.

Not really true, of course, but you get the idea. This one is really true:

Tip: Emacs is much, much, much, much more useful if you know Lisp. Not to mention more fun.

Wrt what to learn:

  1. symbols (they are simple objects, with properties -- not just identifiers)

  2. lists -- cons cells, list structure (including modification/sharing)

  3. evaluation

  4. function application

  5. regexps

  6. text/overlay/string properties (values can be any Lisp entities)

  7. buffers and windows

Drew
  • 29,895
  • 7
  • 74
  • 104
2

I'd suggest you'll take a look what the two Info manuals included with Emacs Emacs Lisp Intro "An Introduction to Programming in Emacs Lisp" and Elisp "The Emacs Lisp Reference Manual" already have to offer and then decide what you would like to add to or do differently than those.

Rörd
  • 6,556
  • 21
  • 27
  • The difference is in the structure of the book. I am trying to make it possible for someone who knows no elisp to learn with 'Always Working Code'. Neither of those two manuals work in that fashion. I find myself poring over them cryptically trying to work out what they mean. Debugging code the first time you use a language is very difficult. Normally debugging is about making the code proper (and you know what proper is). Starting off debugging is about learning what 'proper' is - and that means understanding what working code looks like. – Gordon Guthrie Feb 02 '11 at 07:53
  • 1
    Having now skimmed over your book, and skimmed over Chassell's Intro to Programming in Emacs lisp, I don't know what you mean by "Always Working Code"? Chassell's code works, doesn't it? It seems to me that your book and his cover very similar territory to me. – Tyler Feb 03 '11 at 20:30
  • Possibly, I only discovered that his book existed 3 weeks into to writing mine. I had never seen it, or heard anyone mention it before. I think the difference will be that mine is a native web property with 'key-words-in-links-anchor-text' and thus will be findable and usable by more people - but that's kind of orthogonal to the content. – Gordon Guthrie Feb 04 '11 at 14:11