Software changes fast! Open source software even faster!

And once you start to update dependencies, libraries and frameworks it never ends… After all the testing and validation you may have done there is no guarantee that the software will keep working afterwards. This is no big deal for small and medium sized projects but becomes a full-time job for larger projects with longer life span which require constant maintenance and enhancements. I’ve seen this time and time again during my work on various projects. Even a simple Drupal based website pops up an update every couple of weeks.

OTOH back porting fixes and keeping stable APIs can be a big business. This is what Red Hat is doing for their Red Hat Enterprise Linux distribution. Nearly all changes are backwards compatible and and the software stack remains stable compared to upstream Fedora or the more upstream projects which comprise it.

Let me say that I don’t like to upgrade. Long ago I was using Debian stable on my computer. Now I use RHEL. No fancy features, no bells and whistles and more important predictable behavior wrt updates and APIs. The same approach I take when developing software. I stay away from the latest and greatest technology simply because it changes too often. I prefer mature frameworks and packages which produce new versions every six months or less frequent. This approach allows me to concentrate on writing code and getting the project done instead of plumbing bugs introduced by the latest package foo version.

All this said I have a very careful approach to upgrades, especially if I’m using an upstream package. I will first look at the changelog if any. Luckily many of the mature projects provide comprehensive changelog records. This is especially true for Perl packages. I’m looking for notices about backward incompatible changes, API breakage, security notices, major bug fixes, changes in behavior and the like. When changelog is not available there’s the commit log. I admit this is not something I usually look at but it happens once in a while. I do this for projects I’m particularly interested in or otherwise following. Doing a content diff is another possibility which usually helps you spot (if you look carefully) some API changes as well. I resort to this if I’m not able to find the upstream source repository or when it is hosted on something ancient like CVS.

Based on all of this I decide to upgrade or not. With careful planning of updates (which version, which moment of time) and testing I manage to minimize the hassle of breaking my projects and spending days fixing bugs afterwards. Instead I use the time to write some code that kicks ass (or at least I hope so).

I’m curious to know what sort of information folks do prefer to have when considering an update? Changelog vs. API diff or seething else? I personally prefer well written Changelog and full list of fixed bugs. Please cast your vote in the comments or visit the survey! Thank you!

I was thinking of starting a project similar to Marmalade to alleviate its problems, but then the MELPA project was brought to my attention. This project follows the Homebrew (unofficial OSX package manager) model of using simple GitHub collaboration to maintain and grow a bunch of build recipes. In the case of MELPA, those recipes show how to bundle upstream source packages into package.el-compliant packages. The recipes can be tested locally by package authors, and they are run hourly on the MELPA server to create an HTTP package archive that Emacs users can simply add to their 'package-archives list. As Phil Hagelberg said - there’s no reason to drag in complicated dependencies like Node for something that’s essentially a pile of static files. MELPA on the other hand is written mostly in Emacs Lisp and is thus much more comprehensible to casual Emacs hackers.

Most packages currently contained in MELPA are development snapshots, but the project maintainer Donald Curtis and Steve Purcell (aka sanityinc) are working on extending the MELPA build scripts to support stable packages, using upstream version tags.

Adding a new package to MELPA is as simple as adding a few lines of code to the pkglist file in MELPA’s source code repo:

1
2
3

(name :url "<repo url>"
 :fetcher [git|svn|darcs|wiki]
 [:files ("<file1>", ...)])

You simply have to fork the official repo, modify pkglist, send a pull request and package.el compatible packages will be built automatically for you on MELPA’s server (you can also build the packages locally to test if everything is OK with your recipes). Sure it’s not as easy as submitting a package via a web UI, but it’s a much more robust approach. It also eliminates a common problem in Marmalade - there only the original uploader (+ people selected by him) can update a package. Often the original uploaders are very hard to find…

To use MELPA with Emacs 24 (or a recent version of package.el) just add this to your .emacs (or equivalent):

1
2

(add-to-list 'package-archives
'("melpa" . "http://melpa.milkbox.net/packages/") t)

There’s a lot more info regarding MELPA on its official website and I’d rather not duplicate it here.

I would encourage package authors and users to investigate and contribute to MELPA. I’ve already submitted a bunch of packages there and rebased Emacs Prelude to use MELPA instead of Marmalade.

Together we can turn MELPA into the most extensive and robust community-supported package.el repo! Emacs users deserve one of those :-)

For the people that weren’t happy with EmacsWiki - the ones that felt my pain and were looking for a change I present WikEmacs (pronounced wikimacs). It’s a MediaWiki powered Emacs wiki, that will try to bring to the community cleaner, leaner and more up-to-date documentation.

There are only a few guidelines for the contributors there:

• articles should be geared only towards the current and future versions of Emacs (currently 23 and 24) for maintainability’s sake.
• articles should not copy Emacs’s or extension’s official documentation - they should refer to it instead. An overview, some nice pointers, tips and links - that seems like a good article, doesn’t it?
• comments and questions should go to an article’s discussion page

File uploads are disabled on WikEmacs (but image file uploads will probably be allowed soon) - it will never host Emacs extensions of any sort.

There is a Google discussion group here for more general questions regarding the wiki.

Our goal is not to copy over the 8500 articles available at EmacsWiki. It’s to provide a good road map for new users coming to Emacs and enough helpful hints and tips for experienced users. Everyone is welcome to join our efforts.

As far as short term goals go - have a look at the outlined structure of the wiki (on its home page), pick a section that interests you and create/extend/improve it. Our content is licensed with GNU’s Free Documentation License (which is compatible with Wikipedia’s and probably EmacsWiki’s GPL2). Some nice blog articles about Emacs might be converted to wiki articles with permission from their authors. You might find pandoc useful to automatically convert articles from other formats to MediaWiki markup and mediawiki.el to edit articles on wiki from the comfort of your beloved editor.

Thanks to the people that brought us the original EmacsWiki. Thanks to everyone who supported the idea for the new wiki. Thanks in advance to all future contributors.

Some people will undoubtedly see the birth of WikEmacs as a separatist move to fraction the Emacs community. To them I’d like to say that few things in life are as productive as competition. Obviously a lot of people willing to contribute to a new wiki are unwilling to do so for EmacsWiki and vice versa. This is not a contest and there will be no winner. I wish the best of luck to EmacsWiki and its supporters. What I wish for is to give our community the best source of documentation available and the option to choose.

Yesterday I wrote a highly controversial article about the state of the EmacsWiki and suggested a few things we can do to make things better. I got the usual batch of hate mail and some remarks on the poor quality of my English and writing style (which generally amuse me a lot). But I got much more encouraging feedback from a lot of Emacs community members. So here our story continues…

On The Essence of Things

Some people accused me that I don’t even know what I wiki is. To them I’d like to say that a thing is not its dictionary/encyclopedia definition. A thing is what it’s perceived to be. People expect wiki entries to look and behave like those found in MediaWiki or Confluence and not like some mixture of a wiki, forum and irc conversation…

A Word from Our Sponsor

Alex wrote a public response on the EmacsWiki yesterday, that I’d first like to share (since probably more people will see it here, than there). I publish it here with no alternations:

Bozhidar Batsov is apparently very frustrated with Emacs Wiki. He
seems to think that we should start over – use new software, add
moderators, guidelines, and sorts of fancy stuff. My answer is the
same as it was back in 2008 (http://www.emacswiki.org/emacs/MissionRant).

One of his ideas I actually agree with. “Submit documentation only to
the official project pages.” Absolutely. :)

Some ideas I am luke warm about: “package something on Marmalade…”
Sure, why not? I have never used Marmalade, but I encourage you to
improve the tools you use. There’s also “don’t respond to any bug
requests regarding modified copies of your sources distributed via
EmacsWiki.” I also don’t want to encourage bug reports on the
wiki. Use the facilities built into Emacs to report bugs. But almost
all of you know that.

But other ideas?

“Drop the current format of the wiki - use something standard like
MediaWiki instead of OddMuse.” How is reformatting the pages going to
improve them?

“Drop all the articles about Emacs extensions.” Just delete them? Are
you at least going to rewrite them and move them to the appropriate
project pages out there? Or are you just going to delete them? Taking
away and not giving back?

“Drop all the extensions hosted there.” Some of the old code has no
other home. Some of the old code is here for the poor sods stuck with
Emacs 20. Are you going to package them for ELPA or Marmalade or
whatever you are going to suggest instead?

Some of you – like Drew Adams – keep their packages on the wiki. For
those packages, I don’t see any alternative. Are you going to maintain
his software? Fix his bugs? Develop his features? Unless you are, I
guess you can try and fork his stuff and keep it on whatever other
system you want. But please don’t suggest taking something away
without giving something in return.

“Assemble a team of moderators.” Indeed. Moderators! Where have you
been hiding for the last ten years! Are you volunteering? I’m a bit
wary regarding your deletionist tendencies. But perhaps you’d like to
start with a new Table of Contents and new top-down menus where only
the pages you personally vetted and checked are listed. That would be
an awesome thing to do! Of course, there’s no need to delete anything
in order for you to do this. Just arrange the stuff you like and do
it.

In fact, in order to do it, just do it.

“Accept only articles about general Emacs usage and Emacs Lisp
programming.” How is that going to work – more deleting? I don’t
know… I don’t think you understand where the value of Emacs Wiki
comes from. Perhaps you should write a book about Emacs? Collect a
team of authors and editors and deletionists, take a copy of the wiki,
and just do it right.

Also, less hyperbole when posting… :P

Here’s my two cents on the letter:

• The markup format hardly matters. A new wiki engine would give us better structure of the wiki as whole (like separate discussion pages for one).

• Dropping it from the wiki doesn’t mean we’ll delete the code forever. What I meant was - dump all the extensions to some archive for the interested parties and remove them from the wiki. You’re basically putting words in my mouth.

• We should care for the bad choices some people made (like Drew - all my respect to his work). With so many free project hosting services I don’t feel we’ll be taking something away and not giving an alternative.

• No, I don’t volunteer. Not for this format of the wiki. But I do volunteer for an alternative matching the outline I’ve suggested.

• Mocking me is not right response, you know. The problem exists, you fail to acknowledge it, but I don’t care that much.

• Alex calls it hyperbole, I call it the simple truth (and many others would second me).

The Plan

Many people commented that my post is not worth a damn if I’m not willing to back it with action. I’m sad to disappoint my critics - but I’ll willing to go the whole nine yards on this one. Here’s the outline of my proposal for a new wiki:

1. Use MoinMoin as the wiki engine. It’s written in Python and it’s GPL software. It doesn’t use a database, it’s featureful and mature. It’s successfully used by Debian and Ubuntu (and many other respectable software organizations). I’m against using a Git backed systems since it will increase the entry bar for user participation. I’m even more against the use of a custom platform developed specially to serve as the EmacsWiki.

2. I’ll pay for the hosting and the new domain and set up the wiki initially. I’d suggest that the new project begins with the domain emacswiki.net or emacswiki.info and eventually we’ll assume the old emacswiki.org domain as well (should the new wiki be successful enough). Suggestions for another name are welcome in the comments section.

3. I and anyone willing to lend a hand will pick the articles worth saving from the EmacsWiki and migrate them to the new one. I and anyone willing to serve as moderator will monitor new contributions afterwards.

4. Wiki entries will have a more or less standard structure and will adhere and community established guidelines.

5. The old EmacsWiki will eventually be retired to another domain such as old.emacswiki.org (or similar) for historic purposes and benefit of users of old Emacs versions.

It this good enough for you to call it an action plan? Comments on it are most welcome!

Epilogue

I’m sorry that I’m the guy that has to break the terrible news to all of the delusional EmacsWiki supporters out there - It’s not special. It’s not a beautiful or unique snowflake. It’s the same decaying wiki matter like some many else. I’m sorry for my terrible English and my lack of good manners. I’m sorry I’m willing do to something while so many of you are just whining and ignoring the existing problems.

I think as a member of the Emacs community I’ve shown my worth so far and I’ll willing to do even more. But I cannot carry out such a massive undertaking on my own. I encourage everyone serious about helping out to comment the article (here, not on reddit or hacker news) or send me a personal email.

Update

The new wiki is now available at http://wikemacs.org. It’s using MediaWiki (it turned out it had several nice advantages over MoinMoin).

Emacs is slowly, but firmly moving in the right direction with Emacs 24. A lot of new important features are coming, the release date is nearing, but there is something worrisome on the otherwise bright Emacs horizon. It’s a remnant from the Dark Emacs Days and it’s called EmacsWiki.

Shortly put - EmacsWiki is a blight.

A Little Bit of Background

Here’s the longer story. EmacsWiki was created by Alex Schroeder (aka kensanata) way back (in 2001) with the goal to become the home of all the Emacs information one would ever need (both about Emacs in general and its extensions). I have to admit that this was a noble goal and I know that Alex had all the right intentions, but unfortunately right intentions rarely are enough for things to always move in the right direction.

The software behind the wiki is called OddMuse and it’s authored by Alex himself. It’s pretty basic Perl script and doesn’t feature db support. Its motto is No MySQL; no PostgreSQL; no worries. - wish it were true…

The Problems

The EmacsWiki has several epic problems. Here we go:

Odd Choice for a Wiki

Even if in the beginning OddMuse might have been a good choice (Alex authored it and MediaWiki didn’t exist back then), it hasn’t been a good choice for quite a while. There are much better solutions in terms of markup support (Markdown anyone?), usability and performance. Some of the features of the wiki are simply abhorring - like the lack of user access control; anyone can enter any user name and edit the wiki… Yep, this is not a joke…

Moderators, Where Art Though?

I’ve never seen so much junk in a wiki in my entire life (and I’ve seen the wikis of 15-year enterprise systems). When I was an Emacs beginner I often consulted the wiki for advice - even then I noticed that there were some suspicious practices being suggested there. Now I can say with certainly that much of the content there is total bullshit - it’s mostly written by people with very little knowledge of Emacs (not to mention good Emacs practices). The articles are littered with crappy advice confusing beginners, have little structure and are filled with ridiculous questions (questions in an wiki???). All of this would have been avoided had the EmacsWiki had a team of moderators to keep shitty contributions at bay. Alas, such a team does not exist (or does a very crappy job of it).

Software Distribution Medium

As crazy as it seems a lot of people are using the wiki as a software distribution mechanism. Instead of hosting their projects in version control (say GitHub) they develop stuff locally, upload them to the wiki and say that this is the canonical way to obtain their software. Needless to say - this is a horrible, horrible practice. I’ve often encountered on the wiki source files authored by someone, then edited by 10 different guys, that have a tendency to add their names to the copyrights sections instead of thinking how their poor users will understand what exactly was changed in these files. Sometimes the authors themselves are to blame (for being fucking lazy), but often someone just copies a snapshot of a project from version control and uploads it to the wiki, creating problems of epic proportions for the maintainers, who start receiving bugs about stuff they never developed in the first place.

For the love of God - take your project(s) to GitHub and develop them there with pleasure, under the scrutiny of an active and passionate developer community. Wikis should be used for documentation only!

Tools like audo-install (an extension that supports installing software from EmacsWiki) should never have existed. el-get should not have added support for the installation of stuff from the wiki. As long as such practices are tolerated they will not stop.

Need I remind you that we’re now living in the era of package.el and distributed version control (Git, Mercurial, Bazaar)? Act accordingly!

Jack of All Trades

Documenting each and every Emacs project is an impossible task. And it should not be centralized. Each project should be responsible for producing its own up-to-date easy-to-follow crystal-clear documentation. By putting everything in one place you’re just making sure you’ll end up with a pile of out-of-date confusing unstructured ramblings (the EmacsWiki proves my point).

An EmacsWiki shouldn’t list tips on the use of external projects - such tips should be in the project’s wiki. An EmacsWiki should document the core Emacs experience and customizations only.

The Solution

Kill the EmacsWiki! (may it be reborn from its ashes)

Action Plan for The Maintainers

Drop the current format of the wiki - use something standard like MediaWiki instead of OddMuse. Drop all the articles about Emacs extensions. Drop all the extensions hosted there. Assemble a team of moderators. Accept only articles about general Emacs usage and Emacs Lisp programming.

Action Plan for Emacs Extensions Authors

If you’ve got a normal project hosted on GitHub (or a similar service) - delete everything about your project on the wiki and don’t respond to any bug requests regarding modified copies of your sources distributed via EmacsWiki.

If you’ve got a project hosted on the EmacsWiki - there is still a chance for you to redeem yourself. Migrate your project(s) to GitHub (you’ll thank me later for that). Use their version control, their issue tracker, their wiki system. Start distributing your project via Marmalade or MELPA (package.el repos). Your life will become much nicer and the visibility of your project and the possibility to attract new developers will be significantly boosted. GitHub is a project hosting solution, the EmacsWiki is not.

The Regular Users

Boycott the wiki (unless the maintainers take actions)! Submit documentation only to the official project pages. Ignore projects hosted on the EmacsWiki. (or migrate them to GitHub if they seem orphaned and try to rekindle them)

Epilogue

Do we need an EmacsWiki? Certainly we do! But we need a real EmacsWiki and not this abomination that is currently a detriment to new Emacs users, instead of help. The wiki needs restructuring, but first it needs to die. I hope you’ll see the truth in my words and take action instead of commenting how outrageous my claims are. Do something meaningful for a change - save a project from the EmacsWiki, contribute documentation to an official project’s wiki, package something on Marmalade…

Die, Die EmacsWiki! I’ll be seeing you in hell…

Update

This post stirred a huge discussion online and as a result there is now another Emacs wiki out there. The new wiki is available at http://wikemacs.org. It’s using MediaWiki (it turned out it had several nice advantages over MoinMoin).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

;; use shift + arrow keys to switch between visible buffers
(require 'windmove)
(windmove-default-keybindings 'super)

;; automatically save buffers associated with files on buffer switch
;; and on windows switch
(defadvice switch-to-buffer (before save-buffer-now activate)
  (when buffer-file-name (save-buffer)))
(defadvice other-window (before other-window-now activate)
  (when buffer-file-name (save-buffer)))
(defadvice windmove-up (before other-window-now activate)
  (when buffer-file-name (save-buffer)))
(defadvice windmove-down (before other-window-now activate)
  (when buffer-file-name (save-buffer)))
(defadvice windmove-left (before other-window-now activate)
  (when buffer-file-name (save-buffer)))
(defadvice windmove-right (before other-window-now activate)
  (when buffer-file-name (save-buffer)))

Obviously this code could have been written in a more compact manner with the use of a macro, but I’ve decided to use this more verbose variant for the sake of simplicity. We assume that you want to auto-save your current work (buffer) when you switch to a new buffer or to a new window (with either C-x o (other-window) or a windmove command).

XEmacs has a hook called deselect-frame-hook that can take the concept even further, but it’s absent from GNU Emacs.

So, that’s all for this tip, folks! I hope you’ve enjoyed it! Personally I find it much more useful that the standard auto-save mechanism in Emacs. And one more thing - Emacs Prelude naturally enables this functionality by default.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

$ rake -T
rake clean                 # Clean out caches: .pygments-cache, .gist-cache, .sass-cache
rake copydot[source,dest]  # copy dot files for deployment
rake deploy                # Default deploy task
rake gen_deploy            # Generate website and deploy
rake generate              # Generate jekyll site
rake install[theme]        # Initial setup for Octopress: copies the default theme into the path of Jekyll's generator.
rake integrate             # Move all stashed posts back into the posts directory, ready for site generation.
rake isolate[filename]     # Move all other posts than the one currently being worked on to a temporary stash location (stash) so regenerating the site happens much quicker.
rake list                  # list tasks
rake new_page[filename]    # Create a new page in source/(filename)/index.markdown
rake new_post[title]       # Begin a new post in source/_posts
rake preview               # preview the site in a web browser
rake push                  # deploy public directory to github pages
rake rsync                 # Deploy website via rsync
rake set_root_dir[dir]     # Update configurations to support publishing to root or sub directory
rake setup_github_pages    # Set up _deploy folder and deploy branch for Github Pages deployment
rake update_source[theme]  # Move source to source.old, install source theme updates, replace source/_includes/navigation.html with source.old's navigation
rake update_style[theme]   # Move sass to sass.old, install sass theme updates, replace sass/custom with sass.old/custom
rake watch                 # Watch the site and regenerate when it
changes

Not only did you get a list of all the tasks, but nice descriptions of the tasks as well.

For instance - if you want to execute the er/expand-region command (part of the expand-region package) a few times you can do it like this:

1
2
3
4
5

M-x er/expand-region
C-x z
z
z
z

Neat, ah?

Let’s face it - although a vanilla Emacs installation is quite powerful almost nobody is using Emacs without a pile of add-ons. And managing those add-ons is quite frankly a pain in the ass. Traditional options included installing Emacs add-ons via the operating system’s package manager (if available), downloading .el files from various locations (everybody hates packages distributed only on Emacs Wiki with no canonical version control repo) and simply sticking them on the load-path, etc. It’s more than obvious that such solutions are less than ideal.

For instance if you’re installing Emacs add-ons via a package manager and you have to change OSes (or machines) you’re mostly fucked. On the other hand piling files manually in .emacs.d is equal to hell in the version and dependency tracking department. There has to be a better way, right? Wouldn’t it be nice if Emacs had its own package manager similar to the likes of homebrew, apt or yum?

Emacs 24 finally introduces such a tool - its name is package.el (very original, right?) and it’s promise is to make you’re lives a bit easier. Does it manage to deliver on that promise? We’ll see that in a bit…

Package management with package.el

package.el is bundled with Emacs 24, but it’s not bound to Emacs 24. Before it became part of Emacs it was an external package, known as ELPA (I guess that stood for Emacs Lisp Package Manager or something similar). So even if you’re an Emacs 23 user you can copy the latest version of package.el from here and enjoy it. At this point you’ll have to do something like:

1
2

(require 'package)
(package-initialize)

Put this snippet of code near the beginning of your Emacs config, since you’ll definitely want packages installed via package.el to be initalized before you start tweaking them.

What package.el basically does is that it connects to a list of package repositories, retrieves the list of the packages there, presents it to you in a interactive fashion and lets you install the packages you like (of course you can also remove the once you don’t like). package.el understands the dependencies between packages and if one package requires others to run they will be installed automatically (which is really neat).

The magic starts with the command M-x package-list-packages. At this point you should see something in the lines of this.

You can navigate the list of packages, mark the ones you want to install with the “i” key or the ones you want removed with the “d” key and when you’re done you can press the “x” key to execute the scheduled actions.

Initially package.el didn’t provide the option to update a package, but that should be fixed in recent Emacs builds. According to this thread you can even update all of the installed packages by using the “U” key in the packages list view (I guess that a small “u” would update only one package). Unfortunately my build is lacking those capabilities so I cannot comment of their usability.

You’d probably notice that your list of available packages is not particularly long. That’s because the official Emacs 24 package repository has a strict licensing (and source code) requirements to include a package there. Luckily there are a number of community-maintained package.el repos around with much more relaxed requirements. Probably the most popular of them is Marmalade, created by Nathan Weizenbaum of Sass and Haml fame. You can include it in your package-archives list like this:

1
2

(add-to-list 'package-archives
             '("marmalade" . "http://marmalade-repo.org/packages/") t)

Marmalade provides a web based UI for package upload and search (both quite buggy unfortunately) and the ability to share the maintenance of a package between several people, who’ll be able to upload new version of the package. There’s also a Emacs Lisp Marmalade tool, that allows you to submit packages directly from Emacs.

Using the package.el UI is ok if you’re a casual Emacs user, but what if you have a custom Emacs configuration, stored under version control, that you’d like to instantly deploy on any OS/machine (like Emacs Prelude). Here in play comes package.el’s programmer interface. In Emacs Prelude I use the following code to install a list of required packages automatically on Emacs startup (if necessary):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

(defvar prelude-packages
  '(ack-and-a-half auctex clojure-mode coffee-mode deft expand-region
                   gist groovy-mode haml-mode haskell-mode inf-ruby
                   magit magithub markdown-mode paredit projectile python
                   sass-mode rainbow-mode scss-mode solarized-theme
                   volatile-highlights yaml-mode yari zenburn-theme)
  "A list of packages to ensure are installed at launch.")

(defun prelude-packages-installed-p ()
  (loop for p in prelude-packages
        when (not (package-installed-p p)) do (return nil)
        finally (return t)))

(unless (prelude-packages-installed-p)
  ;; check for new packages (package versions)
  (message "%s" "Emacs Prelude is now refreshing its package database...")
  (package-refresh-contents)
  (message "%s" " done.")
  ;; install the missing packages
  (dolist (p prelude-packages)
    (when (not (package-installed-p p))
      (package-install p))))

(provide 'prelude-packages)
;;; prelude-packages.el ends here

This code check if all of the packages in the list are installed and if any of them are not installed if refreshes the local package database (in the case a required package for recently added to the remote repo) and installs them.

To be able to publish a package to Marmalade (or another repo) it should comform a standardized structure. A single-file package might look like this:

1
2
3
4
5
6
7
8
9
10
11
12

;;; sass-mode.el --- Sass major mode

;; Copyright 2007-2010 Nathan Weizenbaum

;; Author: Nathan Weizenbaum <nex342@gmail.com>
;; URL: http://github.com/nex3/sass-mode
;; Version: 3.0.20
;; Package-Requires: ((haml-mode "3.0.20"))

;; Code goes here

;;; sass-mode.el ends here

A multi-file package should have an additional file named <name>-pkg.el that should look like this:

1
2
3

(define-package "sass-mode" "3.0.20"
                "Sass major mode"
                '((haml-mode "3.0.20")))

The Bad and the Ugly

While package.el is great on paper, for it to really take off some problems need to be resolved.

Updating should be easy

One of the best features of OS package managers is that they make it really easy to update all of the installed packages to their latest versions. Currently package.el doesn’t support that (at least to my knowledge), with the exception of the “U” key in the list packages view. This seems to me like a pretty basic feature and I (and everyone I’ve talked with) would really like to see it in Emacs 24 final.

Too much is riding on Marmalade

Marmalade has become extremely important in the recent months and the list of packages there is growing every day. This would have normally filled me with great joy, if it weren’t for a few problems.

It seems that the project isn’t getting much attention from its maintainer (which is understandable, given the fact that he’s maintaining several high profile projects + the fact he’s a full time Google employee). As a result Marmalade is quite buggy (especially in the UI department) and is missing key features, like the ability to contact a package maintainer. At some point it was even lacking the ability to delete a package. Uploads don’t work reliably there, package refresh sometimes yields http errors that require manual M-x package-refresh-contents and from time to time there is even downtime of the service.

The fact that its backend is written in Node.js (great technology, but not widely understood for now) and hosted on Google Code, doesn’t improve the situation a lot. A Ruby or Python based solution hosted on GitHub would certainly gain much more traction in the community (and I’m planning to start work on one soon).

Scarce documentation

package.el is light on the documentation and you’ll have to explore its source code if you want to implement its required interface (which luckily is very simple). I hope this will change by the release of Emacs 24.

Too few package authors care about package.el

Package authors rarely tag versions that could be uploaded to a package.el compatible repo and from time to time don’t follow the basic structure required. I always contact package authors to let them know of such shortcomings in their packages and so should you.

Alternatives

el-get is another popular Emacs add-ons management solution that has recently become popular.

el-get allows you to install and manage elisp code for Emacs. It supports lots of differents types of sources (git, svn, apt, elpa, etc) and is able to install them, update them and remove them, but more importantly it will init them for you.

That means it will require the features you need, load the necessary files, set the Info paths so that C-h i shows the new documentation you now depend on, and finally call your own :post-init function for you to setup the extension. Or call it a package.

el-get is inherently troublesome piece of software on Windows machines and was originally designed to make it simple to obtain the latest versions of packages from git - a practice which I profoundly dislike. Master package branches are often buggy (but there are also authors that never tag versions and rely on the rolling release model) and I’m generally supportive of the stable version releases. While some view it as a nice addition to package.el I feel that el-get is too low level tool (in its approach to the problem) and should be avoided.

Update

A few hours after I posted this article it got a nice lengthy comment by el-get’s author. Since I believe, that the comment is quite interesting I’m adding it here without any alterations.

As the author of el-get, good article! The Emacs extension situation
is far from ideal and needs hard critics so that work is done to
improve it.

I now want to share with you some of the features that are currently
only available in the development branch of el-get (soon to be
released as 4.1): you can now easily checkout a stable branch from a
git repository (thanks to the :checkout property) and you can even
setup which checksum you want installed.So when using git, the
checksum is in fact a revision, when using emacswiki you have to
compute the checksum (doing M-x el-get-checksum) and register it in
your el-get-sources setup, then if the file change on emacswiki el-get
will refuse loading it (hopefully until you’ve done your review then
updated the checksum).So while I perfectly understand your reserve
toward depending on el-get, I believe that your concerns are being
solved now.I would like to believe that authors of emacs lisp scripts
would take the time to consider formatting their sources for
package.el. Today it’s far from granted, so by choosing ELPA you miss
a lot of things. And for the situation to change you need to have the
authors willing to package their extensions, or you have to fork their
work. With el-get you have access to 536 packages from the get-go, and
all of emacswiki (that’s currently more than 1700 packages) after
you’ve done M-x el-get-emacswiki-refresh. As of writing this comment,
my M-x el-get-package-list contains 2106 packages ready to install,
almost all with descriptions.el-get is about social packaging where
it’s easy to prepare a recipe for a package, whatever distribution
means its author picked. Then you can share that recipe very easily,
for example with el-get on github where we’ll be happy to add your
work and have it installed by default when users either install el-get
or do M-x el-get-self-update.As for windows support, it all depends on
the packages you want to install. Most of them just work out of the
box, being a single emacs lisp file (.el). Some of them require to
have extra tools installed, from git or svn or mercurial to make and
autoconf. That’s only how the authors are shipping their extensions
though, el-get is only providing for an integrated way to get at it.
We have accepted several improvements so that the windows experience
matches the others OS, and we consider windows a first class citizen
here.

Epilogue

package.el is the future of Emacs add-on management - of that I’m quite certain. It’s far from perfect, but even in its present flawed form it has already simplified the life of many Emacs users immensely. I urge all of you to stop distributing Emacs packages via sources such as the Emacs Wiki and to put a heavy emphasis on package.el. Make your packages compatible with it, upload them to a community maintained repo (or the official if possible) and keep them up-to-date. Your users will love you for that!

I’d like to see a replacement to Marmalade in the future as well. A more robust and polished solution, maintained by a team of several people. Hopefully that moment is not that far in the future.

If there is something that people love as much as tweaking their editing configurations it’s probably the selection of color themes. A good color theme can make your work much more pleasant and a bad one that literally impair your vision. It’s a fact of life that I’m a firm supporter of low-contrast color themes with dark backgrounds - I find them easy on the eyes and I feel that they don’t strain the eyes as much as most themes. I’ve even ported a couple of popular themes to Emacs - Zenburn and Solarized.

In this short article we’ll see how color theming has changed in Emacs 24 and I’ll share with you a few tips on theme creation and distribution.

Color Theming in Emacs 24

Prior to Emacs 24 the most popular way to incorporate custom color themes into Emacs was the color-theme package. While it usually got the job done it had some problems that I won’t be discussing here and more importantly - it’s a third-party package, that’s not part of Emacs proper.

Emacs 24 finally introduced a new standard way of dealing with color themes (based on Emacs’s built-in customize facility). While it doesn’t have a proper name (as far as I know) it’s commonly referred to as the deftheme facility, since deftheme is the name of the macro you’d use to create such a theme. ( deftheme has actually been around since Emacs 23, but it was heavily improved in Emacs 24 )

Emacs 24 comes with a selection of built-in themes that you can choose from, so you’re no longer bound to the default theme (which I find quite ugly). To choose a new theme just do a M-x load-theme (tab completion is available for the names of the available themes). At this point you can give the command a try with the tango theme. If you like a theme so much that you’d want to use it all the time you can put in your Emacs configuration (.emacs or init.el for instance) like this:

1

(load-theme 'theme-name t)

If you’d like to return to the default-theme just do a M-x disable-theme.

How do you create a deftheme theme? Quite simply actually - just do a “M-x customize-create-theme”. You’ll be presented with an UI prompting you for a theme name, description and faces. After you save the theme a file called name-theme.el will be written on your filesystem. Here’s its skeleton:

1
2
3
4
5
6
7
8
9

(deftheme demo
  "Demo theme")

(custom-theme-set-faces
 'demo
 ;;; list of custom faces
 )

(provide-theme 'demo)

There was also an online theme generator here, but it seems to be down at the moment.

Personally I dislike customize a lot, so when I needed to create a Emacs 24 theme for the first time I’ve just opened the source code of the built-in tango theme and used it as a reference.

Once you’ve created the new theme you’ll have to drop it in a folder that’s on the custom-theme-load-path. I’d suggest the following:

1

(add-to-list 'custom-theme-load-path "~/.emacs.d/themes")

If you’re an Emacs Prelude user you’re already covered. This folder exists and is automatically added to custom-theme-load-path by Prelude, so all you have to do is drop there the themes you’d want to try out.

You may find the rainbow-mode useful when developing color themes. If fontifies strings that represent color codes according to those colors. The mode is known to be a great addition to css-mode, but I find it very helpful with color theme development as well. It’s also included (and enabled) in Prelude by default. Here you can see it in action.

The Emacs package manager package.el (formerly known as ELPA) is gaining a lot of popularity lately and the community Marmalade repository already houses a few Emacs 24 themes that you can install from there. If you’re developing a theme that you’d like to submit to Marmalade it’s imperative that the theme modifies the custom-theme-load-path in an autoload - otherwise it won’t be of much use. Add the following snippet (or something similar) before the provide-theme line if your custom theme:

1
2
3
4

;;;###autoload
(when load-file-name
  (add-to-list 'custom-theme-load-path
               (file-name-as-directory (file-name-directory load-file-name))))

I’d also advise you follow the proper naming convention name-theme.el so that it’s apparent that your theme is deftheme compatible.

Oh, and one more thing - porting themes from color-theme to deftheme is really simple (just have a look at the old and the new version of Zenburn in its repo), so you should really consider porting all the themes you maintain to deftheme.

Epilogue

Color theming in Emacs has never been easier. It’s time to kill color-theme once and for all. If you’ve ever developed a color theme for it I urge you to convert it to the deftheme format and upload it to Marmalade.

And if you’ve never developed a color theme for Emacs because you were afraid it was too hard - now is the time to do it.

So without further ado here’s a screenshot of the theme (or the dark variant to be precise):

Note that this is a very early version and I haven’t fine tuned all the colors yet. The source code and installation instructions can be found on GitHub.

The theme is already bundled in Emacs Prelude and I’ll submit it to Marmalade soon. Note that I’ve dropped some things like the degraded palette and the 16 color palette (at least for now), since I doubt many people need them. On the other hand - you’ll proper coloring in most prominent modes out of the box.

Feedback, suggestions and patches are always welcome.

Anyone who’s ever dabbled in the dark art that is Emacs knows that chances are you’ll be overwhelmed before you start making sense of Emacs’ unique view of the world. There is just too much information out there…

There are many great Emacs resources targeting different groups of Emacs users. The problems is that often the people that would benefit the most from some of those resources don’t even know about their existence. That’s why I’m putting together this article - to collect the best resources in a single location and categorize them accordingly. Surely I’ll miss a lot of stuff - I’m just one man and I certainly don’t know about many great repositories of Emacs wisdom. I hope you’ll help me by pointing out such repositories in the comments section. So here we go…

Emacs Squires (Beginners)

The Emacs Tutorial

Built into Emacs itself this should be the first thing you ever read about Emacs. The tutorial is interactive (you get to play with concepts after you read about them) and you can start it at any point (provided you’ve started Emacs first) by pressing C-h t.

The Emacs Refcard

The Emacs Refcard is a very useful resource to keep tugged under your keyboard (in printed form). It’s generally bundled with your Emacs installation in both pdf and tex formats, but I’ve included a hyperlink to spare you the search for it.

The Emacs Reference Mug

The Emacs Reference Mug is basically a refcard printed on a tea mug. Let’s you memorize keybindings while enjoying a delightful cup of English Breakfast…

Mastering Emacs

Mastering Emacs is a relatively new web site (it just celebrated it’s first birthday), dedicated to teaching Emacs to beginners. It has some really nice articles to get you started and a nice reading guide to go alongside them. Mastering Emacs features a few articles, covering more advanced topics as well.

Emacs Fu

Emacs Fu is a blog discussing little (and not so little) tweaks to make working with Emacs even nicer. Its author has been an Emacs user for the last decade or so and certainly has a lot of interesting tips and tricks to share from you. Even I happen to learn something new from Emacs Fu from time to time.

Meet Emacs

Meet Emacs is a great introductory Emacs screencast by PeepCode. It’s not free, but if you prefer screencasts over reading manuals you should definitely have a look at it.

Programothesis

Programothesis is an YouTube channel dedicated to Emacs. It features over 30 short Emacs screencasts covering various topics.

Learning Emacs

Learning GNU Emacs is the last book that was ever published about Emacs. It’s a bit dated now (the last edition is from 2004), but Emacs doesn’t change that fast and you’ll still find a lot of relevant info into the book. This was the second resource I’ve read about Emacs (after the built-in tutorial) and while I didn’t find the book outstanding I did find it very helpful.

Emacs Rookie

Emacs Rookie is a web site dedicated to Emacs tips (mostly about beginners). There are only a few articles there right now, but hopefully their number will grow substantially over time.

Emacs Rocks

Emacs Rocks is a series of short Emacs screencasts. While some of the things suggested there make me grind my teeth, there are also quite a bit valuable suggestions that you’ll find in the short videos.

Emacs Prelude

Emacs Prelude is a custom Emacs 24 configuration developed by me and optimized for your joy and productivity. It’s a good starting point for anyone looking to get started with Emacs without too much initial research and ceremony. I’m always looking for ideas on extending and improving Prelude.

Emacs Starter Kit

Emacs Starter Kit is a custom Emacs configuration similar to Prelude. The stable version targets Emacs 23 and ESK 2.0 targets Emacs 24 and makes heavy use of the new Emacs Lisp Package Manager (ELPA) introduced there. I’m obviously much more fond of Prelude, but it’s only fair that I mention the competition as well (ESK has been around much longer and is a more stable project by all means).

An Introduction to Programming in Emacs Lisp

Although Emacs Lisp is usually thought of in association only with Emacs, it is a full computer programming language. You can use Emacs Lisp as you would any other programming language.

Perhaps you want to understand programming; perhaps you want to extend Emacs; or perhaps you want to become a programmer. This introduction to Emacs Lisp is designed to get you started: to guide you in learning the fundamentals of programming, and more importantly, to show you how you can teach yourself to go further.

It’s also built into Emacs - you can access it by typing C-h i m Emacs Lisp Intro. The book is very light reading and doesn’t assume any programming experience. If you’re an experienced software engineer the Emacs Lisp Manual might be a better place to start you Emacs Lisp adventure.

On Twitter

There are a few Twitter accounts dedicated on Emacs. I recommend you to follow @emacs_knight(operated by yours truly), @learnemacs, @EmacsRocks, @dotemacs and @dotemax. My personal account is listed in the sidebar - while I do tweet about Emacs there from time to time, I mostly tweet about programming so follow me at your own discretion.

On IRC

There is a irc.freenode.org channel named #emacs. I highly recommend you to hang around there - a lot of great Emacs hackers are permanent residents of the channel and will kindly answer most questions you might have about Emacs.

Given that Emacs has a great IRC mode built-in (that would ERC) you have little excuse not be in #emacs. My handle there is bozhidar (I know - total surprise, right?).

Emacs Knights

Effective Emacs

Effective Emacs is a popular post by Steve Yegge in which he discusses a few techniques to make more effective use of Emacs. I don’t fully endorse them, but still there a few great tips in there.

A Gentle Introduction to CEDET

If you’re doing any C/C++ programming you owe it to yourself to read Alex Ott’s excellent article A Gentle Introduction to CEDET.

Emacs Wiki

The Emacs Wiki is the one stop to find answers about all topics related to Emacs. The Wiki, however, is poorly moderated and in a state of total chaos and disarray. This makes it a bit hard to sift through all the crap there and extract only the really valuable bits of information. The amount of wisdom collected on the wiki is impressive never-the-less and every experienced Emacs user should browse it numerous categories for tips and tricks.

Perhaps surprising for some - the Emacs Wiki is housing a huge collection of Emacs Lisp source files as well. I have a personal appeal to all the people using the wiki to house their Emacs Lisp projects - “For the love of God - use GitHub!”.

The Emacs Manual

The official Emacs Manual is one of the greatest Emacs resources ever written, but only a handful of Emacs users seems to have read it. It’s built into Emacs itself and you can start perusing it simply by typing C-h r. While it’s a hefty volume, the Emacs Manual has one serious advantage over the competition - it’s always up-to-date.

The Emacs Lisp Reference Manual

If you’re serious about extending Emacs - this is the book to read. It’s targeting experience developers, it’s always up-to-date and it’s the ultimate Emacs Lisp resource in the world. It’s also available for reading directly from Emacs itself - C-h i m Emacs Lisp.

Planet Emacsen

Planet Emacsen is a RSS feed aggregating most well-known Emacs blogs out there (including this one). If you’re serious about Emacs you have to subscribe to it.

Mentioning it also spares me the need to list all those great blogs in here.

Emacs Masters

Understanding SLIME

Understanding SLIME is an excellent overview of SLIME, featuring a myriad of links to great SLIME resources. You should see the SLIME video tutorial even if you don’t read anything else from the article.

SLIME Tips

SLIME Tips is a blog dedicated to sharing little know features of SLIME with the rest of us. Seems to be dormant, but started off pretty nice…

Practical Common Lisp

Common Lisp? We’re talking about Emacs, right? Strange or not I found more about Emacs Lisp, while studying Practical Common Lisp, than the bundled Emacs Lisp manuals. For me the explanation is simply - Practical Common Lisp helped me get the Lisp way of thinking. There is also the cl module is Emacs that implements a good deal of Common Lisp in Emacs Lisp and I use it all the time. I, personally, dream of an Emacs using Common Lisp (or at least Scheme) instead of Emacs Lisp, but doubt I’ll live to see such beast.

How to Tackle all that stuff?

Well, there is no universal formula. What follows is just my personal suggestion.

Squires

If you’re an Emacs beginner start from the Emacs Tutorial and proceed with the articles on Mastering Emacs. Get a copy of Emacs 24 and Emacs Prelude to start off with a solid initial configuration.

Study the rest of the resources at your own discretion. Following Twitter accounts has very low overhead for you and could be very beneficial.

Knights

Read the Emacs Manual. Read the Emacs Lisp Manual. Subscribe to Planet Emacsen. Read the source code of Prelude or the ESK. The rest is totally up to you.

Masters

Read the Emacs source code. Contribute bug fixes and new modes. Share your knowledge. Sharpen your Lisp skills.

Epilogue

The road to Emacs mastery is a long and tiresome one. But it’s also one of the most enjoyable roads one may choose to travel. Hopefully you’ll enjoy it even more armed with the many resources I’ve listed here.

In the beginning of the article I said I’m certainly going to miss many great bits of Emacs wisdom. I’d like to ask you to mention them in the comments section so that I could add them to the article.

1
2
3
4

some_word = "word"
some_other_word = some_word

some_word.equals? some_other_word # true

Both == and eql? implement value equality checks - they are not interested in whether two variables point to the same object in memory, but whether two objects are equal in terms of their values. For instance “cat” and “cat” might very well be two completely different String objects, but they are quite obviously the same as far as their value is concerned.

1
2
3

"cat".equals? "cat"    # false
"cat" == "cat"         # true
"cat".eql? "cat"       # true

What’s not immediately obvious is why are there two different methods that seem to be doing exactly the same thing. The answer is simple - eql? is meant to be used as a stricter version of ==, if there is a need for such stricter version.eql? most prominent usage is probably in the Hash class, where it’s used to test members for equality.

In the Object class eql? is synonym with ==. Most subclasses continue this tradition, but there are a few classes that provide a different implementation for eql?. Numeric types, for example, perform type conversion across ==, but not across eql?, so:

1
2
3
4
5

1 == 1       # true
1.eql? 1     # true
1 == 1.0     # true
1.eql? 1.0   # false
1.0.eql? 1.0 # true

As you can see clearly from this example - eql? for Numeric classes requires both objects to be instances of the same class, apart from having equal values, to return true.

If you’re wondering about the origins of that convention I should probably refer you to Common Lisp (one of the languages cited as principle inspiration for Ruby). Common Lisp has quite a few equality predicates, dealing with various aspects of equality. I guess I never found == and eql? in Ruby particularly confusing, because I knew Common Lisp, before I started playing around with Ruby.

Hopefully, I’ve managed to make the difference between == and eql? clear. That’s some fairly esoteric matter that’s not totally understood by even some fairly experienced Ruby developers.

Emacs, naturally, wants to help with every problem possible and provides a very nice solution in the form of the whitespace-cleanup command. It’s a much more powerful alternative to the older delete-trailing-whitespace command, that simply deletes trailing whitespace, and it’s aware of the whitespace-style variable, used by whitespace-mode.

It usually applies to the whole buffer, but in transient mark mode when the mark is active, it applies to the region. It also applies to the region when it is not in transient mark mode, the mark is active and C-u was pressed just before calling whitespace-cleanup interactively. There is also a similar command called whitespace-cleanup-region.

The problems cleaned up are (borrowed from the official documentation):

1. Empty lines at beginning of buffer.

2. Empty lines at end of buffer. If whitespace-style includes the value empty, remove all empty lines at beginning and/or end of buffer.

3. 8 or more SPACEs at beginning of line. If whitespace-style includes the value indentation: replace 8 or more SPACEs at beginning of line by TABs, if indent-tabs-mode is non-nil; otherwise, replace TABs by SPACEs. If whitespace-style includes the value indentation::tab, replace 8 or more SPACEs at beginning of line by TABs. If whitespace-style includes the value indentation::space, replace TABs by SPACEs.

4. SPACEs before TAB. If whitespace-style includes the value space-before-tab: replace SPACEs by TABs, if indent-tabs-mode is non-nil; otherwise, replace TABs by SPACEs. If whitespace-style includes the value space-before-tab::tab, replace SPACEs by TABs. If whitespace-style includes the value space-before-tab::space, replace TABs by SPACEs.

5. SPACEs or TABs at end of line. If whitespace-style includes the value trailing, remove all SPACEs or TABs at end of line.

6. 8 or more SPACEs after TAB. If whitespace-style includes the value space-after-tab: replace SPACEs by TABs, if indent-tabs-mode is non-nil; otherwise, replace TABs by SPACEs. If whitespace-style includes the value space-after-tab::tab, replace SPACEs by TABs. If whitespace-style includes the value space-after-tab::space, replace TABs by SPACEs.

It might be a good idea to add whitespace-cleanup to your before-save-hook so that every buffer would be cleaned up before it’s saved:

1

(add-hook 'before-save-hook 'whitespace-cleanup)

Often in comparisons between Django and Rails, one of the Django advantages being cited is the automatic admin interface you get for free out-of-the-box there.

I guess a lot of people don’t know that there are similar solutions for Rails, although they are not included in the standard distribution. Currently the two most prominent admin UI ‘frameworks’ are RailsAdmin and Active Admin.

While they are both shooting to solve the same problem, they do it in a very different way. Many new users are quite confused what advantages/disadvantages one has over the other (and vice versa) and that’s the reason I’m writing this article right now - to clarify a few vague points and to help people choose the framework most appropriate for the task at hand.

RailsAdmin

RailsAdmin started its life as a port of MerbAdmin to Rails 3 and was implemented as a Ruby Summer of Code project by Bogdan Gaza with mentors Erik Michaels-Ober, Yehuda Katz, Luke van der Hoeven, and Rein Henrichs. The project is self described as a Rails engine that provides an easy-to-use interface for managing your data..

Its main features include:

• Display database tables
• Create new data
• Easily update data
• Safely delete data
• Automatic form validation
• Search and filtering
• Export data to CSV/JSON/XML (very handy)
• Authentication (via Devise)
• User action history

RailsAdmin currently supports only ActiveRecord as the ORM. You can see a live demo of RailsAdmin here.

The current master branch of RailsAdmin targets Rails 3.1.x and it’s naturally aware of the asset pipeline introduced there. Installing RailsAdmin is a trivial exercise. Just add these deps to your Gemfile:

1
2

gem 'fastercsv' # Only required on Ruby 1.8 and below
gem 'rails_admin', :git => 'git://github.com/sferik/rails_admin.git'

Afterwards you should run:

1
2
3

$ bundle install
$ rails g rails_admin:install
$ rake db:migrate

And you’re done. RailsAdmin uses internally the tried and true Devise for admin users authentication. If you’re already using devise - you’re covered, otherwise RailsAdmin will install it for you.

At this point you can boot your development web server (rails s) and visit the url localhost:3000/admin (or whatever port you’re running the dev server on). You’ll be able to create admin accounts and after you log in you’ll be presented by an attractive admin dashboard, that shows you an overview of all the tables in your model.

By default you’ll be able to manage every single model in your app. You’ll have to customize the contents of config/initializers/rails_admin.rb to change that default behavior.

One thing to note is that there are no gem releases of RailsAdmin. It’s still alpha quality software (at least on paper - it’s quite stable actually). I’m generally a bit annoyed to have to track gems from a git repo, but I understand and respect the developer’s decision on the matter. Hopefully we’ll see a stable release of RailsAdmin soon enough and a gem to go with it.

Another thing to keep in mind is the use case for RailsAdmin - it is pretty much an automatic backend, that you’re not supposed to modify a lot. In its spirit it’s very close to what Django’s admin backend is. RailsAdmin is very smart in determining the relations between model and supplying forms and show views that express them properly.

Unfortunately not all relationships are represented correctly and modifying the form builders in RailsAdmin is no walk in the park. Another minor annoyance is that CarrierWave is not supported out of the box so you have to do some manual tinkering in the RailsAdmin initializer to make it work.

Some of the nicer touches in RailsAdmin include basic integration with CKEditor (a rich WYSIWYG editor) and an user action feature, which helps keep track of who did what. I wouldn’t mind seeing some mention of TinyMCE as an alternative to CKEditor in the docs, since it’s considered more robust by many (yours truly included).

The docs themselves are just a big README in the project’s github repo. While they feature most of what you’ll need to know about RailsAdmin, having them organized in a nicer way (something that the guys behind Active Admin have done) wouldn’t hurt.

Active Admin

Active Admin is the other big Rails admin UI framework, developed by Greg Bell. Its official web site describes it like this:

Active Admin is a Ruby on Rails plugin for generating administration
style interfaces. It abstracts common business application patterns to
make it simple for developers to implement beautiful and elegant
interfaces with very little effort.

Active Admin is of course Rails 3.1 ready, plays nice with the asset pipeline and has great documentation on its official web site. There also a very nice introductory screencast by Ryan Bates from RailsCasts.

Getting started with Active Admin is just as easy as getting started with RailsAdmin. You just need to add a dependency to your Gemfile:

1

gem 'activeadmin'

And to a few command line incantations afterwards to seal the deal:

1
2
3
4

$ bundle install
$ rails g active_admin:install
$ rake db:migrate
$ rails s

Fire up your favorite browser and visit localhost:3000/admin. The default username is admin@example.com and the default password is password. You’d probably be surprised to see an empty dashboard and absolutely no models that you can administer. Active Admin takes a totally different approach compared to RailsAdmin. Here nothing happens automatically - you have to customize your dashboard yourself and you have to register the models you’d be administrating with the following command:

1

$ rails g active_admin:resource ModelName

This will create a file named app/admin/model_name.rb where you can tinker with looks of the resource’s index, form and show view.

And here comes Active Admin’s core feature - it’s immensely easy to customize anything in the Admin UI. The forms used to create and update model records are simple Formtastic forms (the same Formtastic forms you’re probably already using throughout the rest of your apps):

1
2
3
4
5
6
7
8
9
10
11
12
13

ActiveAdmin.register Post do
  form do |f|
    f.inputs "Details" do
      f.input :title
      f.input :published_at, :label => "Publish Post At"
      f.input :category
    end
    f.inputs "Content" do
      f.input :body
    end
    f.buttons
  end
end

Rendering a partial for the form is also supported.

Active Admin features an elegant DSL to express the index and the show views. Here’s an example of index table for a fictional Course Management app:

1
2
3
4
5
6
7
8
9
10
11

ActiveAdmin.register Course do
  index do
    column :id
    column :title
    column :start_date
    column :end_date
    column :created_at
    column :updated_at
    default_actions
  end
end

The default_actions method invocation here is important - without it you’ll be missing the action buttons in the last column of the index table.

Here’s an example of a show view:

1
2
3
4
5
6
7
8

ActiveAdmin.register Post do
  show do
    h3 post.title
    div do
      simple_format post.body
    end
  end
end

Alternatively you can forgo the Arbre HTML DSL and render a partial like this:

1
2
3
4
5
6

ActiveAdmin.register Post do
  show do
    # renders app/views/admin/posts/_some_partial.html.erb
    render "some_partial"
  end
end

The documentation is very well written and quite extensive so I wouldn’t go into many details here (remember DRY). The only issue I’ve had with Active Admin so far is not related to Active Admin directly - the latest gem release still depends on the old Formtastic 1.3 and I happen to use Formtastic 2.0 in all of my apps. Luckily the master branch is already using Formtastic 2.0, so all you have to do if you have this problem is to use the gem from git:

1

'activeadmin', git: git://github.com/gregbell/active_admin.git

If you’re reading this article after the release of Active Admin 0.4 (which should happen any day now) - you don’t have to do this.

Which Should You Use

The answer to that question depends on your needs for a particular project.

RailsAdmin is still alpha. Unstable developments are made in topic branches and master is supposed to be as stable as possible. RailsAdmin is not an admin scaffolder as is Active Admin. It’s an automatic backend. It’s goal is to provide a full access to your data, with maximum of defaults extracted from application’s ORM/ActiveModel, a DSL to customize those, and hooks for third-party projects (Cancan/Devise/Paperclip/CKeditor) to enrich the experience. Granularity is higher in RA. You are not supposed to access FormBuilder the way you would with Active Admin and Formtastic. RailAdmin says here It’s in the dev field, not configuration. Still, the current blackbox has some flaws, discrepancies and uncovered areas that its developers are currently addressing.

Active Admin basically does things the other way around. You’re totally supposed to tweak every aspect of the Admin UI - but tweaking those aspects is very very easy. If you’re looking for a heavily customized Admin UI solution - Active Admin is certainly the way to go. It’s not an automatic admin backend by any means - it’s more or less a framework that simplifies the creation of admin UIs.

In terms of popularity it seems that RailsAdmin is a bit more popular right now. I consider the GitHub watchers of a project to be a fairly accurate measurement of its popularity and as of the time of this writing RailsAdmin has 2539 compared to 2127 for Active Admin. You have to consider the fact that RailsAdmin has been out in the open a bit longer. Active Admin is rapidly closing this gap, however, and I expect it to surpass RailsAdmin in a month or two.

My personal recommendation is to start by trying RailsAdmin - if it covers your use cases, you’d do well to simply use it instead of pouring additional effort into creating a similar UI with Active Admin. If you need heavily customized admin UI, however, you’d probably do well to start with Active Admin in the first place, since after all - it was designed for such scenarios.

Epilogue

Having used both RailsAdmin and Active Admin with real projects I can tell you that they serve a different purpose - the admin UI generated by RailsAdmin is quite usable by default and might be used with very little changes. Active Admin’s admin UI generally requires manual tweaking to achieve the same effect. On the other hand Active Admin was developed with manual customization in mind at it’s very easy to do such changes there. Modifying the forms in RailsAdmin was definitely a less pleasant experience (not to mention stuff like CarrierWave integration).

While there are some people urging the projects to merge I think that would be a terrible idea. Aside from the technical difficulties of merging separate projects sharing no common codebase, I do think diversity matters. Rails has virtually no alternatives (in Rubyland) and that is bad for business, since competition always drives innovation. I’d love to see both projects evolve in their current directions (and stabilize along the way).

So what are you waiting for? Give them both a shot and share your experience in the comments section! :-)

If you are a professional writer – i.e., if someone else is getting paid to worry about how your words are formatted and printed – Emacs outshines all other editing software in approximately the same way that the noonday sun does the stars. It is not just bigger and brighter; it simply makes everything else vanish.

I’m an Emacs user and I’m proud of the fact. I know my reasons for using it (and loving it) for many years now. But many people don’t. I often get asked by various people the same question - “Why should I use Emacs? What makes it better than Eclipse/IntelliJ/vim/etc?”.

While I wouldn’t dare to claim that Emacs is better than all the IDEs and competing editors I’ll share here the things that I think are making it great. But first…

A Text Editor in 2011 - Are You Mental or Something?

The simple fact is that the popularity of programmer’s text editors is not as high as it once was. With so many integrated development environments flying around traditional text editors like Emacs and Vim seems to have fallen out of grace with the mainstream users/programmers and are mostly used by enthusiasts and old school hackers these days.

For all the good things IDEs have brought us (smart auto-completion, nice visual debuggers, semantic analysis of the source code, etc) they have totally forgot about the most crucial part of software development - it’s mostly about editing text. And all the IDEs I’ve used have extremely poor text editing capabilities compared to likes of Emacs and vim. A very trivial example is the fact that most IDEs don’t even have keybindings optimized for touch typing - they require you to move your hands often from the home row (such a waste) and have mouse-centric UIs.

A programmer’s editor might not have all the fancy bells and whistles - but it has the thing that matters (should matter) the most - a decent editing experience.

The Road to Emacs

I was not always an Emacs user. And wasn’t always an Unix user either. My journey to computing started in the nineties when I was doing some basic programming with Pascal in the Turbo Pascal environment, notorious for its horrible editing features. Afterwards I was drawn to the allure of C and C++ combined with Microsoft’s Visual Studio IDE. At first I felt it was like magic - so much of the source code got generated by various wizards and I felt productive. Felt is the key word here. At some point, however, I noticed that all the wizard started to become annoying - I already knew what they were about the generate and sometimes I even had a better idea about the details of a particular piece of code. Writing code manually at some point always becomes more productive than clicking through wizards.

Then I’ve started my first professional gig in a company solely devoted to FreeBSD, C and Perl. I had never used an Unix system before and I captivated by the fact how much of its internals were open for the user to tinker with and how many small tools were working together to achieve a greater goal. I was also captivated by the editor that all my colleagues in the company were using - vim. It was both simple and profound - minimalistic UI, handy terminal support, plain-text configuration, keybindings 100% optimized for touch typing and it had so many cool editing features. I’ve used vim for a couple of years, but two things about it always bothered me - dealing with many files was no fun (at least back than - as far I know vim 7 has made some improvements in the area) and vimscript (the extension language for vim) simply sucked.

I had often heard rumors of a mythical editor so powerful and some infinite in its capabilities that people were afraid to approach it. That editor’s name was Emacs. When I first started Emacs I had absolutely no knowledge of Lisp what-so-ever, so dealing with it’s configuration in the beginning was a bit hard - I often copied some bits and piece of code that I didn’t fully understand and when there was an error within some of those snippets, I was having a really hard time figuring it out. Luckily for me I found a copy of Learning Emacs - a nice (but not great) book that gently guided me through the maelstrom of Emacs features. At first I was hardly efficient in Emacs, but my proficiency in it quickly grew.

I had a bit of luck that I switched jobs and went to work in a company where Emacs had God-like status. All the cool devs there were using it and they were also hardcore Lisp hackers. There I learned the true power of Emacs, there I got hooked to Lisp and there I truly understand what Emacs is about.

Emacs is what you want it be. Emacs is power. But with great power, comes great responsibility - the responsibility to think.

Why Emacs?

Enough small talk, let’s talk business… Here’s a brief overview of the things that make Emacs special (at least to me).

Divine Editing Experience

You can easily navigate around text buffers, perform all sorts of editing operations with a snap, without ever leaving the comfort of the home row of your keyboard.

Emacs has support for some pretty fancy stuff like rectangular editing, kill-ring (something like an internal clipboard history), mark-ring (you can set points of interest in a buffer you can later revisit), etc.

Everything is Possible

Emacs has got a mode for that!

Naturally every popular programming language is well supported under Emacs (with the notable exception of PHP, which has once of the lamest Emacs modes I’ve ever seen). Most not-so-popular programming languages are well supported as well.

The quality and the features vary wildly though - some modes like SLIME, cc-mode, js2-mode and cperl-mode are nothing short of magical and others provide only basic highlighting and indentation support.

But this is only the tip of the iceberg - in Emacs you can easily create beautifully typeset documents and books in LaTeX (with the help of AUCTeX mode), charts with graphviz-mode, you can check your e-mail with gnus (wanderlust and mew are other nice options), chat in IRC with ERC, run a terminal session or write your next great blog entry. And so many other things - there is even a coffee-mode that allows you to control certain kinds of coffee machines from Emacs.

I happen to write all the articles on my site in Emacs and I publish them to github pages using the excellent magit (git integration for Emacs).

No matter what the task at hand is - you can rely on Emacs’s superb editing capabilities.

Emacs is Extensible

The GNU Emacs manual describes Emacs as the extensible, customizable, self-documenting, real-time display editor. And with a good reason - it’s extremely easy to add new features to Emacs, due to its integrated Emacs Lisp interpreter.

While there are some core things in Emacs, written in C for efficiency’s sake, almost all the great modes and magic commands are written in a dialect of Lisp, called Emacs Lisp (that is somewhat reminiscent of Common Lisp, albeit lacking many of its features).

What this means is that you get the dynamic nature of Lisp development for all of your Emacs extensions - you can write a small bit of Emacs Lisp code anywhere, eval it and run it right away. There are no tedious compilations steps or huge interfaces that have to be implemented. There is virtually no ceremony. For instance:

1
2
3
4
5
6
7
8
9

(defun prelude-google ()
  "Googles a query or region if any."
  (interactive)
  (browse-url
   (concat
    "http://www.google.com/search?ie=utf-8&oe=utf-8&q="
    (if mark-active
        (buffer-substring (region-beginning) (region-end))
      (read-string "Google: ")))))

This simple bit of code adds to Emacs the ability to invoke Google queries from it (with the help of your favorite browser). After evaluating this code in Emacs you can simply type M-x prelude-google and this new command will be at your disposal.

In Emacs it’s easy to create modes that support programming languages, provide functionality such as IM and email checking, etc.

Emacs Integrates Well with Lots of External Tools

Running a shell from Emacs is easy - M-x shell-mode. Running a terminal emulator in Emacs is just as easy - M-x ansi-term. And there is even a shell written in Emacs Lisp, called eshell, that you can use no matter what the underlying operating system is.

You need a file browser for Emacs - we have plenty! Dired is the tried and try option, but there are “more modern” solutions such as emacs-nav.

Version Control integration? You bet! CVS, SVN, bazaar, git, mercurial - everything is supported out of the box!

You want to invoke a shell commands on the side? Nothing is easier.

You want to invoke make/rake/whatever from Emacs? Done and done.

You can even use Emacs as a process manager (M-x proced).

Emacs Doesn’t Make You Repeat Yourself

Emacs supports everything in the playbook on DRY (Don’t Repeat Yourself). Command repetition, prefix command arguments, keyboard macros, Emacs Lisp functions, etc. I use them all - and I love them all.

It’s Easy to Share an Editing Session Between GUI and Terminal

While many people prefer to do all their editing in the terminal or in a GUI application - I don’t. I spend most of my time in a GUI Emacs frame, but from time to time I occasionally fire Emacs from the terminal to do some quick edit.

Emacs doesn’t start up as fast as vim, so I would be pretty pissed if I had to wait for it to load every time. Luckily it has a feature called Emacs daemon, which allows you to start a headless emacs server to which you can afterwards connect to from both GUI and terminal clients:

1
2
3

$ emacs --daemon
$ emacsclient -c
$ emacsclient -t

emacsclient -c opens up a new Emacs GUI frame, while emacsclient -t fires up a new terminal frame. And the best part - all the buffers currently opened can be shared between as many clients as it pleases you.

You can push the idea a notch further and connect to an Emacs daemon running on a remote machine.

Emacs is Modern

Contrary to what some people say about Emacs - it is a pretty modern piece of software. On *BSD and Linux the GUI is implemented in GTK2/3, on OS X it’s using Cocoa, and on Windows - it’s naturally using WinAPI. Emacs integrates well with the OSes it runs on - for instance the OS’s clipboard is integrated well with Emacs’s kill-ring out of the box. Things like the Trash are also covered.

Emacs supports TTF fonts, has a built-in semantic code parser (called Semantic), features a package manager that allows you retrieve Emacs packages (extensions) from remote locations automatically (think of a tool similar to apt-get or brew for Emacs packages).

Emacs is Constantly Evolving

Emacs has literally evolved before my eyes - when I started using it 7 years ago there was no support for truetype fonts, no Emacs daemon, no built-in Semantic, no GTK2 UI, no package manager, etc. I cannot dare to imagine what exciting changes are about to come…

Other Prominent Tools Use Emacs’s keybindings

Most shells (bash, zsh, etc) use Emacs keybindings by default. Most of the Emacs keybindings are the same as those found in the readline library. Apple’s Cocoa toolkit uses Emacs keybindings as well - I guess this is one of the reasons why so many Emacs users love OSX.

Emacs vs the World

Emacs vs vim

Emacs vs vim. The most epic battle of them all. More epic than Linux vs Windows and Barcelona vs Real Madrid combined… This, however, is no flame post and I’ll not be bashing vim here. I’ll just mention my brief (and highly personal take on the subject).

For me Emacs has these advantages over vim:

• it has better default extension language. I haven’t wrote any vim extension in Python/Ruby, but I can imagine it’s a much more pleasant process than using vimscript.
• it’s modeless - switching constantly between command-mode and editing mode is not very annoying, but I do prefer Emacs’s way
• it has better integration with external systems
• it has better support for the things that matter to me
• it has a built-in package manager
• it has better infrastructure for editing many files in the same session

On the other side vim excels in a few areas for me:

• nicer navigation
• much smaller core and much faster to load
• very simple initial config
• it has a more stylish icon than Emacs ;-)

Emacs vs IDEs

Emacs is considered by many to be the prototype of modern IDEs, but it’s quite different from most of them. IDEs main strengths are good refactoring support, semantic code analysis, integrated GUI debuggers and GUI design tools, precise auto-completions and good integration with external systems such as version control and issue tracking.

IDEs main weakness are their poor editors and their dependency to the mouse and an X environment in general. IDEs in general are not particularly resource efficient either, but I guess that this matters less and less as computers grow more and more powerful. Many people (me included) have tried to use Emacs or vim keybindings in a IDE, but it’s a pointless quest - without all of the features of Emacs/vim a few keybindings are mostly useless.

For me the true problems of IDEs lies somewhere totally else and it’s less mentioned. The IDEs impair your thinking by thinking instead of you. I’ve seen people generate a lot of code with IDEs without ever questioning its workings or quality. When you produce everything manually you’re much more likely to contemplate on its quality and to consider ways to make it more concise and more elegant.

This, of course, is highly subjective - I mean no offense to IDE users in general. I do, however, know very well the APIs I’ve programmed in Emacs and remember less about APIs I’ve programmed in IntelliJ (for instance).

Emacs is not Perfect

Emacs is not perfect, of course. There a lot of things Emacs users would still like to see.

Replace Emacs Lisp with Scheme or Common Lisp

While Emacs Lisp has served Emacs well so far, it’s far from the best Lisp dialects out there. While I’d personally like to see it swapped for Common Lisp I guess this is never going to happen. There was, however, a rumor last year that there is a long term plan to replace Emacs Lisp with Scheme (GNU Guile to be precise). I have absolutely no idea how much of a possibility that is - but I do know that we could use a bit more powerful and a bit more modern extension language.

Improvements to the GUI

While the GUIs in recent Emacs version were much improved there is still much to be desired.

For instance - on OSX it would be nice if Emacs used Lion style scrollbars and had support for the full-screen app mode. On OSX there are some strange Cocoa bugs as well - like linum-mode looking corrupted, etc.

I guess that currently Emacs’s GTK version has the nicest GUI of them all, but it would good of the Windows and OSX port got some more love.

Multi-threading

Emacs is a single-threaded app and this is problematic, since tasks that block that one thread for an extended period of time (like email checking) tamper with Emacs’s responsiveness. Multi-threading support is certainly coming to Emacs, but I cannot speculate with a time-frame. I guess it will be part of Emacs 25 and we’re least a few years away from it (Emacs 24 is still not released).

Integrate Semantic tightly into Emacs

Currently most programming modes in Emacs are implementing syntax highlighting just by searching for regexp patterns. This is notoriously fragile approach - especially in languages like Ruby, that have a very complex grammar. Basing syntax highlighting on a semantic analysis of the code would be much more robust. Not to mention that it will open the gates for much more advanced features in Emacs programming modes. I’ve read somewhere that such tight integration with Semantic is truly planned. We’ll just have to wait and see (and why not even help?). Of course there is the matter with backward compatibility…

Getting Started with Emacs

OK, I’ve told you some interesting things and I’ve piqued your interest in Emacs. Now you’re probably wondering how can you get started with it. Knowing what I know now - I don’t recommend my personal chaotic approach to mastering Emacs. Here’s a few tips to get you started.

Obtain a copy of Emacs 24

Emacs 23 is old news, Emacs 24 is the future. Take a look at my post Getting Started with Emacs 24 for more details.

Obtain a Decent Initial Config

The default configuration sucks. Luckily there is Emacs Prelude - Emacs 24 configuration that doesn’t suck. I highly recommend you to use Prelude as your initial Emacs config. Studying its source will give you a bit of an insight into Emacs Lisp programming

Read & Practice

• first step - run the built-in Emacs tutorial - C-h t
• second step - watch the excellent screencast Meet Emacs
• third step - visit Mastering Emacs
• forth step - read the official Emacs Manual - C-h r
• fifth step - use Emacs day and night for all your work

Epilogue

Emacs is undoubtedly the most powerful programmer’s editor in existence. It’s a big, feature-laden program with a great deal of flexibility and customizability. As we observed in the Chapter 14 section on Emacs Lisp, Emacs has an entire programming language inside it that can be used to write arbitrarily powerful editor functions.

Should you give Emacs a shot? I have absolutely no idea… If you found something in my post intriguing - I guess you should. If it was to you like the ramblings of mad fanatic with no connection to the real world - probably not.

I truly believe that anyone could gain something positive by spending some time with Emacs and exploring its vision and culture. I guess that in the it all boils down to whether you believe me…

1
2
3
4
5
6
7
8
9
10
11

(defun prelude-open-with ()
  "Simple function that allows us to open the underlying
file of a buffer in an external program."
  (interactive)
  (when buffer-file-name
    (shell-command (concat
                    (if (eq system-type 'darwin)
                        "open"
                      (read-shell-command "Open current file with: "))
                    " "
                    buffer-file-name))))

On OSX it would use the open program to decide which program to open the file with, otherwise you’d be prompted to enter the name of the program in the minibuffer.

I find it convenient to bind the command to C-c o:

1

(global-set-key (kbd "C-c o") 'prelude-open-with)

This command is naturally part of Emacs Prelude.

I’ve started my personal blog some three years ago. Back then in was hosted on wordpress.com and was called devcraft.wordpress.com. I had a lot of interesting (at least to me) topics to write about on my mind, but I was immediately faced with a serious problem - I felt very uncomfortable writing posts in a small text area, using the primitive editing capabilities of a web browser. Ordinary decent hackers love and value two tools above all else - their text editor and their shell. And we love solving problems automatically with clever programs and scripts, instead of manually.

I knew the only way to ever start writing, like I intended, to was to actively involve them in the process. So here my story begins…

In Emacs We Trust

My editor happens to be Emacs and I’ve started to look for ways to blog without leaving its beloved frame. They were several options:

• Use some browser extension that fires up Emacs when editing text areas. For instance in Google Chrome there is the extension Edit with Emacs.

• Use org-mode to write my posts.

• Emacs Muse was another option. Emacs Muse is an authoring and publishing environment for Emacs. It simplifies the process of writings documents and publishing them to various output formats. Muse uses a very simple Wiki-like format as input. Muse consists of two main parts: an enhanced text-mode for authoring documents and navigating within Muse projects, and a set of publishing styles for generating different kinds of output.

• Use some Emacs mode, like weblogger-mode, that allows to write and publish WordPress (amongst others) entries directly from Emacs.

All these options had their merits, but they also had their shortcomings. For one - there is only one writer’s markup that I really enjoy and this is Markdown. This probably has something to do with the fact that I’ve written quite a lot of stuff in GitHub and Assembla using it. I also wanted the ability to easily include syntax highlighted code snippets (since I generally write about programming) and handy way to manage blog updates - preferably via git. I push something to my repo and voila.

At the time I couldn’t make up my mind and my blog was left with a few quite short posts, due to my inability to withstand being in wordpress for any prolonged period of time.

Then something extraordinary happened in the beginning of this year. I’ve stumbled upon the post “Blogging Like a Hacker” by GitHub’s co-founder Tom Preston-Werner (aka mojombo). It seemed that other people had exactly the same problem as me. It also seemed they were more determined to do something about it.

Along Comes Jekyll

Long story short, Tom had written a blog aware static site generator, called Jekyll in Ruby. Jekyll posts are simply Markdown or Textile files and the Liquid templating language is used to enhance the posts in their post-processing phase. Code highlighting? Jekyll (and pygments) has got your back. Nice, ah? There is support for various layouts and here’s be best part - you could put your blog in a GitHub repo and deploy automatically to GitHub Pages.

I instantly fell in love with Jekyll and as you can see from my archive I’ve finally wrote some nice (arguably) & long articles - like I’ve originally intended.

While I was mostly happy with Jekyll there were a few things that bothered me with it:

• You have to design your layouts yourself. While this is generally fine if you have a sense for design, when you’re someone like me that could yield some pretty ugly designs. I was so out of ideas that I designed my Jekyll layout to look like my Emacs (down to the Zenburn color theme) for which I got a lot of flak.

• Maruku is a really crappy Markdown processor. I wished something like RedCarpet was the default and that fenced code blocks (ala GitHub) were the default option for code highlighting. Not that you can’t replace Maruku with Kramdown or RedCarpet, but still. You’d also have to patch Jekyll to run albino on the markdown files to get the highlighting to work with the fenced blocks.

• You have to do some really boring stuff like Disqus integration, twitter integration, etc manually (or at least you have to manually install some plugins).

• You have to unroll your own deployment scripts, since Jekyll doesn’t bundle any. Trivial task, but annoying non-the-less.

So there you have it - Jekyll is very nice, but it’s also very barebone. My single biggest gripe with Jekyll, however, is that being engineered by a GitHub guy it doesn’t support out of the box the GitHub flavored Markdown. At some point as I was seriously contemplating starting a new static site generator, similar to Jekyll, that supported only RedCarpet as the Markdown processor and by extension - the GitHub flavoured Markdown. It would have some nice default theme and very reasonable default settings for use in a blog. Google Analytics, Twitter, Disqus would be supported out of the box. But I never got to writing it since just before I started I was introduced to Octopress…

Octopress is Jekyll with Batteries Included

Emacs users are typically portrayed like this:

I was naturally amused by the Octopress name.

First and foremost Octopress is Jekyll with batteries included. Some of the nicer things include:

• A semantic HTML5 template
• A Mobile friendly responsive (320 and up) layout (rotate, or resize your browser and see)
• Built in 3rd party support for Twitter, Google Plus One, Disqus Comments, Pinboard, Delicious, and Google Analytics
• An easy deployment strategy using Github pages or Rsync
• Built in support for POW and Rack servers
• Easy theming with Compass and Sass
• A Beautiful Solarized syntax highlighting (though not as beautiful as the Zenburn-one I’m about to release soon)

And did I mention that there are a lot of nice plugins included?

The default theme is quite nice, but you’d probably want to tweak it a bit (I still haven’t - but my sense of design is nonexistent). It’s very easy to modify the theme.

I could go on and write a lot about Octopress, but there is no need to do so. Go visit the official web site - it has fantastic documentation.

Moving from Jekyll to Octopress

Mostly trivial. I’ve just copied my old Markdown posts, adjusted the headings and the code blocks. And in the end all I had to do was:

1
2

$ rake generate
$ rake deploy

Epilogue

I love Octopress! I used to be a sad blogger and now I’m a happy blogger. If you’re feeling like I felt - you should definitely give it a shot. I’ll probably do a few follow up articles with some tips & tricks I’ve picked along the way with Octopress.

Heroku is an amazing cloud hosting solution. It’s extremely well documented, very easy to start with, very stable and provides you with the option to use free hosting for some small applications.

While Heroku is generally known as a Ruby on Rails hosting company, since their acquisition by SalesForce last year, they’ve expanded their deployment options a lot. Currently Ruby, Java, Scala, Clojure, Python and Node.js are all officially supported (on the Cedar Celadon stack) and more will probably come very soon.

All of our company’s applications are using Ruby on Rails 3.1.x and are targeting the MRI 1.9.2. Those two facts are the reason that we’re using Heroku’s Celadon Cedar deployment stack. Celadon Cedar is currently in beta, but it offer a lot of benefit over the old (stable) Bamboo stack (which also support Rails 3.1 apps and Ruby 1.9.2). For instance - Celadon is aware of the Rails 3.1 asset pipeline and can compile the assets automatically when you deploy your apps to Heroku. With Bamboo you have to precompile the resources, which is a very tedious task.

While our experience with Heroku has been very positive in general, we’ve hit some bumps along the road, so I’ve decided to share some of the problems and their solutions with everyone.

Background

There are some things to keep in mind before deploying to Heroku:

• You can’t upload files to Heroku. This means that if you’re using a gem such as CarrierWave (or PaperClip) for file uploads it should be configured to use some cloud storage (e.g. Amazon S3). There is only one writeable folder on Heroku and this is the tmp folder that you should configure as a tmp folder for your uploads as well.

• Your app should run on Ruby 1.9.2 (the Celadon Cedar stack, doesn’t support Ruby 1.8.x).

• Your rake assets:precompile task should (ideally) not invoke any database related operations.

• You should use PostgreSQL as your local development database to avoid potential differences between the production and the development database.

• You should add the heroku gem to your Gemfile.

• You should install the taps gem if you’d like to use heroku db:pull or heroku db:push.

Preparations

Configure CarrierWave to use cloud storage

Here’s a sample carrierwave.rb, that you can put in config/initializers/ folder:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

if Rails.env.test? # Store the files locally for test environment
  CarrierWave.configure do |config|
    config.storage = :file
    config.enable_processing = false
  end
end

if Rails.env.development? or Rails.env.production? # Using Amazon S3 for Development and Production
  CarrierWave.configure do |config|
    config.root = Rails.root.join('tmp')
    config.cache_dir = 'uploads'

    config.storage = :fog
    config.fog_credentials = {
        :provider => 'AWS', # required
        :aws_access_key_id => 'key_id', # required
        :aws_secret_access_key => 'access_key', # required
    }
    config.fog_directory = 'empoweronrails' # required
  end
end

Disable db access during rake assets:precompile

Some gems (like Rails Admin) access the database during the initialization of the app. The app initialization is ran by default when you invoke:

rake assets:precompile

This is not a problem on your development machine, but it’s problematic on Heroku, since the regular database.yml is discarded there. Add this:

config.assets.initialize_on_precompile = false

somewhere near the end of your application.rb file and it will suppress the initialization on precompile.

Enable assets compilation

It’s absolutely required to have this line:

config.assets.compile = true

in your production.rb file if you want your assets to be compiled automatically by Heroku (which I highly recommend).

Use thin or unicorn as the application server

By default, your app’s web process runs rails server, which uses Webrick. This is fine for testing, but for production apps you`ll want to switch to a more robust webserver. I personally use Thin (recommended by Heroku). Add this to your Gemfile:

gem 'thin'

and this to your Procfile (create it if it doesn’t already exist):

web: bundle exec rails server thin -p $PORT

The creation of the Procfile is very important! You can use the foreman gem to test the correctness of the Procfile locally.

Alternatively you can use unicorn. While I haven’t used Cedar with Heroku yet, I’ve read some nice articles, like this one, according to which one can gain significant performance boost with unicorn.

Optimize your slug’s size

Your slug size is displayed at the end of a successful compile. You can roughly estimate slug size locally by doing a fresh checkout of your app, deleting the .git directory, and running du -hsc.

Smaller slugs can be transferred across the dyno grid more quickly, allowing for a faster spin-up speed on your dynos. Generally speaking, any slug under 15MB is small and nimble; 30MB is average; and 40MB or above is weighty. If you find your app getting into the 40MB+ range, you may want to look into some techniques (such as removing unneeded dependencies or excluding files via .slugignore) to reduce the size.

If your repository contains files not necessary to run your app, you may wish to add these to a .slugignore file in the root of your repository.

Deployment

First you should create a Heroku application on the Cedar Celadon stack.

heroku create --stack cedar

This step will automatically add a git remote called heroku to your git repo’s config. Afterwards the deployment is as simple as pushing a branch (e.g. master) to this remote:

git push heroku master

Keep in mind that one Heroku app corresponds to exactly one git branch. We keep a production branch for production deployments and a master branch for development deployments.

The last step is to initialize your database. You have two options - you can either load the db schema or push an existing database:

heroku run rake db:schema:load

or

heroku db:push

db:push takes as an optional parameter the URL of the db to push to heroku in the following format db://username:password@host/dbname. For example the url for a local SomeApp db is probably postgres://someapp:someapp@localhost/someapp. If you don’t supply the URL it will be automatically conjured by inspecting the database.yml file of the project you were in, while issuing the command.

Troubleshooting

If you’re lucky your deployment will go without a hitch and you won’t have to ever read this section of the manual. Most people won’t be so lucky. :-)

Errors during deployment

If you get an error during the deployment process the cause of the problem will be in front of your eyes. Never-the-less here are some of the most common problems:

• missing Gemfile.lock
• Gemfile.lock that doesn’t match the project’s Gemfile (this happens if you have OS specific gems in your Gemfile)
• db access on assets:precompile
• you forgot the run all specs and cucumber scenarios before deployment ;-)

Other errors

Obviously you need to take a look at the stack trace to gain some insight about the nature of the problem. You can do this very easy:

heroku logs

Some of the most common errors you’ll encounter:

• you forgot to run some migration(s)
• you forgot to turn on asset compilation
• you forgot to run all specs and cucumber scenarios before the deployment

Misc

Dealing with the database on Heroku

You can easily apply migrations to the production database. Just run:

heroku run rake db:migrate

If you want to retrieve the production database locally use the following command:

heroku db:pull postgres://username:password@localhost/dbname

If you want to push your local db to production run the following command:

heroku db:push

Be very careful about the last command! It will wipe out and replace the current production database!

Running a console

Running the Rails console on Heroku is astonishingly easy. Just run:

heroku run rails console

Epilogue

Heroku and Rails are moving targets, which causes a bit of a headache from time to time. Hopefully this short article will save some of you some of that headache.

Last month I’ve blogged about the exciting things are coming up in Emacs 24. What I failed to mention originally is that altough Emacs 24 is slated for a Spring 2012 (tentatively) release there is no real reason not to start using it now. You should also keep in mind that it’s feature complete since it officially entered the feature freeze of its development cycle in July 2011.

I’ve been using Emacs 24 for several months now and it has been nothing but rock solid. I guess the only real obstacle currently is that the way to obtain Emacs 24 is not particularly straightfoward/clear, hence this post.

I’ll discuss here the installation and initial configuration of Emacs 24 on OSX, GNU/Linux and Windows.

Installing Emacs 24

OS X

Obtaining Emacs 24 on OS X is really simple. There are two popular ways to do it. The first is to simply download a pretest (or a nightly build) from Emacs for OSX. My personal recommendation would be to get the latest pretest (which is ironically the first pretest as well) from here.

That was really easy, right?

The second easy way to obtain Emacs 24 is via homebrew. Just type the following incantation in your shell and you’re done:

1
2

$ brew install emacs --cocoa --use-git-head --HEAD
$ cp -r /usr/local/Cellar/emacs/HEAD/Emacs.app /Applications/

The second step is optional, but it’s recommended if you like to start Emacs from the launchpad or from Spotlight. Personally I prefer to start Emacs in daemon mode (emacs --daemon), so that I could share a single Emacs instance between several Emacs clients (emacsclient -c/t).

That’s all folk! You may now proceed to the configuration section.

Linux

Given that Linux is more or less the home os of Emacs it presents us with the most installation options. Of course, we can build Emacs from source on every distribution out there, but I rarely bother to do so. Using the distribution’s package manager is a better idea for many reasons - you don’t need to install a build chain and lots of dev libraries, you get updated versions when they are released and you get automated dependency manager, just to name a few.

That said, few distributions include in their primary repositories builds of Emacs 24. Luckily there are some unofficial repos that come to the rescue.

Debian/Ubuntu users should look no further than the amazing emacs-snapshot APT repo. You’ll find installation instructions there for all the relevant Debian and Ubuntu versions out there. High quality, highly recommended builds!

Gentoo users have even less to do, since Emacs 24 can be obtained via the emacs-vcs package in portage, as noted in the official Emacs on Gentoo page.

Unfortunately I wasn’t able to find prebuilt Emacs 24 packages for any of the RPM distros (Fedora, SUSE, Mandriva, etc). Since, I’m Debian user I have to admit that I didn’t look that far, but the source installation is not particularly hard and is always an option.

Windows

There are several ways to obtain precompiled Emacs 24 binaries if you’re a Windows users. The most popular are EmacsW32, Emacs for Windows and of course the official Emacs Windows builds. I’ve ,personally, never used any builds other than the official ones. The unofficial builds usually include installers and various patches that might be of use to some users.

Since I rarely use Windows I cannot give you any more advice on the choice of a binary vendor.

Initial configuration

Installing Emacs has always been the easy part, configuring it properly - not that much. That’s why I’ve created the Emacs Prelude - an advanced Emacs setup specifically for Emacs 24 that has been tested to properly work on OSX, Linux and Windows.

Its installation is dead simple:

1
2

$ git clone git://github.com/bbatsov/prelude.git path/to/local/repo
$ ln -s path/to/local/repo ~/.emacs.d

For Windows Vista/7 the ~(home) folder is C:\Users\<USER>\AppData\Roaming\.

The configuration in the Prelude is commented extensively and will be improved more along the way. Reading it will be an enlightening experience for all new Emacs users.

The Prelude itself is a moving target. I’ve created it recently and I plan to add a lot more cool things very soon, so stay tuned. If you have any problems with it or have feature suggestions - do not hesitate to open tickets and send pull requests.

Epilogue

Now that I’ve shown you how easy it is to get a hold of Emacs 24 and I’ve provided you with a starting configuration there is really no excuse not to switch to Emacs 24. Install it, use it, love it!