About a month ago I decided to write about the book on Emacs Lisp I am writing. I also made it available on Leanpub where you can download the first chapter and pay me to get the (roughly) 40% of the book that is already written.
This post is the first in a series of updates I plan to publish about once per month. Read on if you are curious about the process of writing a book, or want to learn if it is for you, or want to actually help me to write it!
First of all, I’d like to thank all the people who trusted me so far and say that I was surprised and humbled to have so many of you. Now I feel even more encouraged to stick to my writing schedule.
Also, I’d very much appreciate if anyone who actually read any part of the book told me if it was too easy/too difficult/too verbose/too concise etc. Of course, you can’t satisfy everyone, but I have a very specific target in mind when I’m writing: me from about 10 years ago. It was (almost) exactly then when I started learning Emacs Lisp. I read Robert J. Chassell’s An introduction to programming in Emacs Lisp (which is great for beginners, both to programming and Elisp), and had that “what now?” feeling. And now I’m writing a book to help people in a similar situation find their way through the jungle of Elisp. This means that I assume that the readers are intermediate learners. They already know the basics – what let does, what car and cdr are and how lists in Elisp work, what save-excursion is, etc., and now want to be able to do more advanced stuff. There is (of course) some overlap, but I do not repeat a lot of things from Chassell’s book. One of the readers emailed me that my book may be too difficult – if you have an opinion on this, definitely drop me a line! I have tendencies to write long, complicated sentences, and I may gloss over some details obvious to me but not to someone who is closer to the beginning of their journey, so any such feedback might help other readers. (I will obviously reread the book at some point, too – more than once, actually – to flesh out weaker parts etc.)
I’d also like to share my philosophy of writing this book, since I am still not absolutely sure it’s the best one, and it’s not yet too late to make some changes. When I started writing the first drafts (more than 5 years ago), I thought I’d just write whatever I fell like writing and then stitch what I have written together later. Needless to say, this is a very bad approach. (I think I know that better now, having authored or coauthered three other textbooks.)
So the first part of the plan is that I am going to show really useful code instead of some toy examples. Emacs is rather unique in that it actually allows to do useful stuff in half a dozen lines and two functions. This is actually something I did in the first chapter – the first command useful enough to make it sensible to add it to one’s init.el has exactly six lines and uses exactly two built-in functions. It can be made better – in fact, the whole first chapter (which, as I mentioned, is available for free!) is devoted to make it better – but even that first version is fully usable (even if it has some quirks, e.g. interacts strangely with undo).
The focus on useful things has a kind of a drawback, though – it means that instead of introducing concepts in a very orderly way, starting easy and progressing to more advanced ones, I introduce them when they are needed. Of course, the first versions of the commands I show in the book are the simplest ones, and adding features and fixing bad behavior makes them progressively more complex, but it happens a few times that something perceived as “advanced” is introduced before some another, simpler idea. I’d argue that this is actually a good thing – this is how self-teaching programming often works, when you try to solve some real problem and learn along the way. It may, of course, leave strange gaps in your knowledge – you might end up knowing pretty advanced stuff which you happened to need but having no idea about something much simpler which just was never necessary for you – but my hope is that when you gain enough skills and confidence, finding other stuff in the manual and in Emacs sources (not to mention on the internet) will be natural.
Another consequence of my approach is that some parts tend to be long and contain what may look like an endless stream of digressions. In fact, every chapter has a well-defined subject, but it is not some theoretical area of Elisp, but rather a project to complete. Hence there is no chapter or section about “destructive functions” (which are a very important concept not only in Lisp), but I spend a couple of paragraphs explaining their idea (with an example and diagrams) in one of the chapters where I need to construct a list by succesively appending elements to it. (Expectedly, I use the standard idiom of creating a local variable with let, pushing the elements to it and nreverseing it at the end.) There is no section or chapter devoted to interactive declarations, but I introduce different “interactive codes” and also an interactive clause with a list when they are needed. There is no separate section or chapter devoted to ways of finding functions doing things you need (which is extremely important, given how messy Elisp function naming is), but the first chapter is sprinkled with a few tricks helping with that. All this means that my book cannot really be used as a reference material – it is supposed to be read in order, not skipping anything. (More advanced Elisp coders might thus find parts of it boring – but then, the book is definitely not aimed for them. Also, if what you look for is a reference, you should really use the GNU Emacs Lisp Reference Manual.) I might add an index at some point, though. (An alternative would be to make every part devoted to some Elisp construct or idea a separate section, with an entry in the table of contents. That might work, but I just don’t like that idea.)
Ok, that’s enough for today. In the next updates I plan to say more about the actual contents of the book, my writing schedule and the challenges I had when writing the book. Till the next time!
CategoryBlog, CategoryEnglish, CategoryEmacs, CategoryEmacsBook