better documentation, better init sequence

README.md

@@ -7,8 +7,8 @@ process of coming up with a useful Emacs configuration is long and
 difficult. It's this process that separates you from truly taking
 advantage of Emacs's power. I like to refer to this process as the
 **Prelude**. The **Emacs Prelude** has the goal to ease the initial
-Emacs setup process and to provide you with a much more moreful and
+Emacs setup process and to provide you with a much more powerful and
-productive experience that you get out of the box. By using **Emacs
+productive experience than that you get out of the box. By using **Emacs
 Prelude** you're basically getting a "Get me out of the Prelude, I
 just want to use Emacs" card.
 
@@ -22,28 +22,131 @@ Emacs Starter Kit is fairly popular and there is the Emacs Dev Kit
 that I used to maintain. I've decided to abandon the Emacs Dev Kit for
 the Emacs Prelude for two reasons - the unfortunate choice a name (too
 similar to Emacs Starter Kit) and the totally new philosophy I have in
-store for the Prelude.
+store for the Prelude (easy to update, easy to personalize, easy to
+extend, highly modular, highly comprehensible).
 
-## Enhanced language support
+## Getting Emacs 24
 
-## Additional programming languages support
+Obviously to use the Emacs Prelude you have to install Emacs 24
+first. Here's a few tips on doing so:
+
+### 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](http://emacsformacosx.com). My personal
+recommendation would be to get the latest pretest (which is ironically
+the first pretest as well) from
+[here](http://emacsformacosx.com/emacs-builds/Emacs-pretest-24.0.90-universal-10.6.7.dmg).
+
+That was really easy, right?
+
+The second easy way to obtain Emacs 24 is via
+[homebrew](http://mxcl.github.com/homebrew/). Just type the following
+incantation in your shell and you're done:
+
+```
+$ 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](https://github.com/emacsmirror/emacs) 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](http://emacs.naquadah.org/). 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](http://www.gentoo.org/proj/en/lisp/emacs/emacs.xml).
+
+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](http://ourcomments.org/cgi-bin/emacsw32-dl-latest.pl),
+[Emacs for Windows](http://code.google.com/p/emacs-for-windows/) and
+of course the official
+[Emacs Windows builds](http://alpha.gnu.org/gnu/emacs/windows/). 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.
+
+## Enhanced programming experience
+
+The following list will be expanded greatly in the future.
+
+### Additional programming languages support
 
 * Clojure
 * CoffeeScript
 * Haskell
 
-## Additional markup languages support
+### Additional markup languages support
 
 * Markdown
 * Sass
 * Haml
 * Yaml
+* LaTeX
 
-## Misc
+### Enhanced configuration
 
-**Emacs Prelude** uses by default the Zenburn color theme (a personal
+* C
-preference of me and many other hackers), but you can easily disable
+* Common Lisp
-(or replace) it.
+* Ruby
+* Scheme
+
+## Enhanced productivity
+
+## Bundled packages
+
+* auctex (LaTeX editing)
+* clojure-mode
+* coffee-mode
+* deft (note taking)
+* gist (snippet sharing on github.com)
+* haml-mode
+* haskell-mode
+* magit (enhanced git integration)
+* markdown-mode
+* paredit
+* projectile (project management mode)
+* sass-mode
+* scss-mode
+* yaml-mode
+* yari (ri frontend)
+* yasnippet
 
 ## Installation
 
@@ -63,11 +166,45 @@ client like this:
     emacsclient -t
     emacsclient -c
 
+## Personalizing
+
+If you'd like to change some of the setting in Prelude (or simply add
+more) the proper way to do so would be to create Emacs Lisp files
+under the **personal** directory in ~/.emacs.d. They will be loaded
+automatically be Prelude on startup.
+
+Avoid modifying the Prelude config itself - this will make it hard for
+you to receive automatic updates in the future.
+
+## Caveats & Pitfall
+
+### No arrow navigation in editor buffers
+
+This is not a bug - it's a feature! I firmly believe that the one true
+way to use Emacs is by using it the way it was intended to be used (as
+far as navigation is concerned at least). That's why I've disabled all
+movement commands with arrows - to prevent you from being tempted to
+use them.
+
+### What is this terrible default theme?
+
+It's called Zenburn and I (and lots of hackers around) the world find it
+pretty neat (I also happen to be the maintainer of its Emacs port). I
+find the default theme pretty tiresome for the eyes, that's why I took
+that "controversial" decision to replace it. You can, of course,
+easily go back to the default (or select another theme entirely).
+
 ## Known issues
 
 None so far.
 
 ## Bugs & Improvements
-Bug reports and suggestions for improvements are always welcome. github pull request are even better! ;-)
+
+Bug reports and suggestions for improvements are always
+welcome. github pull requests are even better! ;-)
+
+I'd like to include a nice variety of Emacs 24 themes into Prelude -
+so if you've developed (or simply found) one - give me a shout and
+I'll take a look at it.
 
 Bozhidar

init.el

@@ -33,19 +33,27 @@
 
 ;;; Code:
 
-;; on OS X Emacs doesn't use the shell PATH
+;; On OS X Emacs doesn't use the shell PATH if it's not started from
-;; if you're using homebrew modifying the PATH is essential
+;; the shell. If you're using homebrew modifying the PATH is essential.
 (if (string= system-type "darwin")
     (push "/usr/local/bin" exec-path))
 
-(defvar prelude-dir "~/.emacs.d/")
+(defvar prelude-modules-dir (concat emacs-user-dir "modules/")
-(defvar modules-dir (concat prelude-dir "modules/"))
+  "This directory houses all of the built-in Prelude module. You should
-(defvar vendor-dir (concat prelude-dir "vendor/"))
+avoid modifying the configuration there.")
+(defvar prelude-vendor-dir (concat emacs-user-dir "vendor/")
+  "This directory house Emacs Lisp packages that are not yet available in
+ELPA (or Marmalade).")
+(defvar prelude-personal-dir (concat emacs-user-dir "personal/")
+  "Users of Emacs Prelude are encouraged to keep their personal configuration
+changes in this directory. All Emacs Lisp files there are loaded automatically
+by Prelude.")
 
-(add-to-list 'load-path prelude-dir)
+(add-to-list 'load-path prelude-modules-dir)
-(add-to-list 'load-path modules-dir)
+(add-to-list 'load-path prelude-vendor-dir)
-(add-to-list 'load-path vendor-dir)
+(add-to-list 'load-path prelude-personal-dir)
 
+;; the core stuff
 (require 'prelude-ui)
 (require 'prelude-packages)
 (require 'prelude-core)
@@ -66,6 +74,11 @@
 (require 'prelude-scheme)
 (require 'prelude-xml)
 
+;; load the personal settings
+(when (file-exists-p prelude-personal-dir)
+  (mapc 'load (directory-files prelude-personal-dir nil "^[^#].*el$")))
+;; config changes made through the customize UI will be store here
 (setq custom-file (concat prelude-dir "custom.el"))
 (load custom-file 'noerror)
+
 ;;; init.el ends here

modules/prelude-core.el

@@ -47,7 +47,7 @@ Emacs load path."
         (add-to-list 'load-path name)))))
 
 ;; add the first level subfolders of vendor automatically
-(prelude-add-subfolders-to-load-path vendor-dir)
+(prelude-add-subfolders-to-load-path prelude-vendor-dir)
 
 (defun prelude-open-with ()
   "Simple function that allows us to open the underlying
@@ -348,13 +348,13 @@ there's a region, all lines that region covers will be duplicated."
 (defun prelude-recompile-init ()
   "Byte-compile all your dotfiles again."
   (interactive)
-  (byte-recompile-directory prelude-dir 0)
+  (byte-recompile-directory emacs-user-dir 0)
-  (byte-recompile-directory vendor-dir 0))
+  (byte-recompile-directory prelude-vendor-dir 0))
 
 (defun prelude-regen-autoloads (&optional force-regen)
   "Regenerate the autoload definitions file if necessary and load it."
   (interactive "P")
-  (let ((autoload-dir vendor-dir)
+  (let ((autoload-dir prelude-vendor-dir)
         (generated-autoload-file autoload-file))
     (when (or force-regen
               (not (file-exists-p autoload-file))

modules/prelude-ruby.el

@@ -73,7 +73,7 @@
 (add-to-list 'auto-mode-alist '("\.feature$" . feature-mode))
 
 ;; load bundle snippets
-(yas/load-directory  (concat vendor-dir "feature-mode/snippets"))
+(yas/load-directory  (concat prelude-vendor-dir "feature-mode/snippets"))
 
 (provide 'prelude-ruby)