Previous Entry Share Next Entry
Study Emacs with Lisp or natural language?
There was a back and forth between Emacs bloggers Jared Dilettante and Ian Eure about whether Emacs users should write Emacs Lisp code for their own purposes or whether working in Emacs Lisp should primarily be in support of existing modes--and with the mode's documentation thoroughly read. At this point, the argument has fizzled out, but its worth pointing out that a manual for SQL mode doesn't seem to exist. SQL mode, like most Emacs modes, is self-documented well. However, this argument is evidence that it could probably use a manual.

As someone who's neither a trained writer nor a good one, I know that writing in one's own spoken language is difficult. However, writing concise documentation about Emacs can be just as important as writing Emacs Lisp code, if not maybe more so. Writing documentation will give you a deeper understanding of how something works and help you learn things you didn't already know. It's also important because the documentation you write will help someone else to learn how to use Emacs, too.

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.

Don't get me wrong. It's fine to twiddle code. Reinventing the wheel is the basis for higher education and university study and critical to life-long learning. However, writing code and championing your work as a solution only acts to avoid studying and maintaining existing code and risks distracting the Emacs community from progress. In a way, it's almost anti-social.

I know some Emacs hackers think multiple implementations are important, and "I wouldn't have learned as much if I didn't manage my own Emacs package". These arguments are spurious, though. One should be able to earn these same benefits--and more--by joining in on an existing project, rather than forking a new one. It may take more effort but its the right thing to do and is under my column of "best practices".

The GNU General Public License gives the Emacs hacker a lot of freedom, but we all could still use the occasional self-discipline.

  • 1

A good manual is irreplaceable

After knowing a bit of elisp I realise how cheap elisp code can be. Unfortunately some of them end up in Emacs but nobody seems to use them.

A good piece of manual is irreplaceable. Look at LaTeX and CTAN, those manuals are the best in open source community.

My biggest gripe with emacs...

is the constant referrel to self documenting code. I use emacs constantly.. but I won't say the code is self-documenting. When I am going over a piece of some module I feel like I am reading through some version of Beowulf. Most of the time I am using emacs to do other things (code bash/config management scripts, write RPM spec files, filling out my expense reports, etc.) and Lisp has become more of a background thing that my little knowledge of has died out.

So I agree 100%. Emacs needs manuals, examples and books that go over how to play with it so that it doesn't become that thing programmers who used tons of ram did before Eclipse.

OpenID isn't working too well. This is smooge. thanks for keeping emacs going.

Re: My biggest gripe with emacs...

No, I wouldn't say, "the code is self-documenting", either. Emacs has facilities for self-documentation--Doc strings for variables and functions, describe-mode, describe-bindings, and of course Info manuals. However, it's up to the programmer to use them, and use them effectively.

I agree, again. Just because you write something in Emacs Lisp, there's no reason people will know what it does.

Quoted out of nonsense

The poster has apparently read my essay as an attack on their blog. This couldn't be further off. The examples mentioned in the counter-argument to my post--extending Emacs overlays, custom menus, or Comint mode--only prove my point. Further, Jared concurs with me by stating that Emacs deserves good documentation, and that it doesn't have enough documentation. I think the space to build a bigger community of Emacs Lisp writers and of building documentation is Emacs Wiki. See the Elisp Cookbook for example.

  • 1

Log in