Feeds:
Posts
Comments

Posts Tagged ‘documentation’

My Emacs Goals

Interesting – there is another guy talking about how people should focus their efforts on fixing and improving core libraries rather than writing their own code.

Documenting Emacs also improves your Emacs Lisp skills because you’ll likely be reading other hacker’s Emacs Lisp code. Most important of all you’ll be working on existing code for Emacs rather than making more when it is not entirely necessary to reinvent the wheel.

I guess my last two posts, which have been more self-indulgent rambling than code demonstration, have muddied the purpose of this blog. Let me try and explain where I’m coming from. Then in future posts I can get back to the important thing which is talking about code.

What do I want [from this blog]?

I don’t want to become a super emacs coder primarily because the effort required is too great. There is no documentation other than the code that gets me from where I am to there. And to be honest I don’t care about hacking on emacs core.

My [unrealistic?] goal is to get more people to write emacs lisp. Not necessarily good emacs lisp but any emacs lisp. Why? Because that leads to more discussion, more libraries, better documentation and more people writing emacs lisp. It is a virtuous circle.

And if you don’t get anyone in on the first rung of the ladder, for sure you won’t be getting new guys hacking on the core libraries either.

What have I done about that?

I’ve written about a couple of libraries and APIs that are available and techniques to solve simple emacs problems that are accessible to any programmer, not just one who is steeped in the emacs way.

And I think I’ve done a pretty good job.

If I want to know how to use overlays, and even what they are where are the best places to look (the answer – my lens which covers a practical use of emacs overlays). If my blog didn’t exist, the only option people have to learn about this stuff is to read some fairly dry documentation or the code itself.

What about comint, my favourite library? Again, either my db mode lens or my comint post. An example that is not mine: emacs fu is the best place to learn about custom menus and numerous other little emacs features.

Unfortunately a blog isn’t an ideal place for documentation. But I do keep the list of archives up to date. And one day I’ll make a half decent index page.

Other places to go for a good introduction to emacs are Xah Lee’s Emacs stuff and of course the Emacs Wiki.

Do you want to know why there are so few elisp programmers? Its because emacs is "self-documenting". That basically means "we can’t be bothered to write documentation".

Take a look at perl, php, python. The documentation is good, extensive and centralised and there are numerous examples and discussions of how to do things. And perhaps not coincidentally, all of those languages are orders of magnitude more popular than elisp. That should be the model to aim at.

And a good start might be to translate parts of PLEAC to elisp. I’ll take a look at that.

Read Full Post »

So Ian Eure mistrusts my code because he thinks I don’t read documentation1. Nice. In fact, I did read that page before I implemented db mode. "Fantastic" I thought, "just what I need".

(sql-mode)
(sybase-mode)
select count(*)
  from person
go

And what is the response from emacs?

No SQL process started.

Well gee, so much for the documentation2. At this point I figure that feature doesn’t work correctly and implement my own code, the core of which takes around 10 minutes.

Please understand that I’m not blaming the sql-mode author. It is probably obvious to him (and others) that you need to start the database before you start sql-mode. And I couldn’t help him improve his documentation beforehand either as I didn’t know what the problem was.


1. What is true is that I actually don’t read it particularly well.

2. Yes, I’m aware now that it only works in the opposite order.

Read Full Post »

Follow

Get every new post delivered to your Inbox.