#+TITLE: Emacs Starter Kit #+SEQ_TODO: PROPOSED TODO STARTED | DONE DEFERRED REJECTED #+OPTIONS: H:2 num:nil toc:t #+STARTUP: oddeven #+begin_quote 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. -- Neal Stephenson, "In the Beginning was the Command Line" #+end_quote * Introduction :PROPERTIES: :CUSTOM_ID: introduction :END: This should provide a saner set of defaults than you get normally with Emacs. It's intended for beginners, but provides a good elisp initialization structure for all levels of users. The main advantage of this Emacs Starter Kit are - better default settings - inclusion of many useful libraries - "literate" customization embedded in Org-mode files - an organizational directory structure - git provides for version control, backup, and sharing The latest version is at http://github.com/eschulte/emacs-starter-kit/ ** Learning :PROPERTIES: :CUSTOM_ID: learning :END: This won't teach you Emacs, but it'll make it easier to get comfortable. To access the tutorial, press control-h followed by t. The [[http://emacswiki.org][Emacs Wiki]] is also very handy. ** Installation :PROPERTIES: :CUSTOM_ID: installation :END: 1. Install Emacs (at least version 22) Use your package manager if you have one. Otherwise, Mac users should get it [[http://www.apple.com/downloads/macosx/unix_open_source/carbonemacspackage.html][from Apple]], or install it directly from [[http://savannah.gnu.org/projects/emacs/][from source]] following the instructions in =nextstep/INSTALL=. Windows users can get it [[http://ftp.gnu.org/gnu/emacs/windows/emacs-22.3-bin-i386.zip][from GNU]]. 2. Checkout a version of the starter kit using git -- if you're new to git checkout this [[http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html][git-tutorial]], also we'd highly recommend that you try out [[http://zagadka.vm.bytemark.co.uk/magit/magit.html][magit]] the Emacs mode for git interaction which comes bundled in the starter kit. #+begin_src sh git clone http://github.com/eschulte/emacs-starter-kit.git #+end_src 3. Move the resulting directory to =~/.emacs.d= [1] 4. Install the Org-mode [[http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#submodules][submodules]] with the following #+begin_src sh cd ~/.emacs.d/ git submodule init git submodule update #+end_src 5. build Org-mode #+begin_src sh cd src/org/ make #+end_src 6. build [[http://www.gnu.org/software/auctex/][auctex]] -- for installation help see the [[http://www.gnu.org/software/auctex/manual/auctex/Installation.html#Installation][auctex installation instructions]], auctex requires a working TeX installation #+begin_src sh cd src/auctex ./configure && make #+end_src 7. Launch Emacs! After setup you may need to restart Emacs a couple of times while it downloads packages from [[* Emacs Lisp Package Archive][ELPA]] -- errors parsing html from =*tromey.com:80*= can generally be safely ignored. If you are missing some autoloads after an update (should manifest itself as "void function: foobar" errors) try M-x regen-autoloads. If you want to keep your regular ~/.emacs.d in place and just launch a single instance using the starter kit, try the following invocation: #+begin_src sh emacs -q -l ~/src/emacs-starter-kit/init.el #+end_src Note that having a ~/.emacs file might override the starter kit loading, so if you've having trouble loading it, make sure that file is not present. ** Structure :PROPERTIES: :CUSTOM_ID: structure :END: The init.el file is where everything begins. It's the first file to get loaded. Additional customization embedded in this file provides what I consider to be better defaults, both for different programming languages and for built-in Emacs features like bindings or registers. Files that are pending submission to [[* Emacs Lisp Package Archive][ELPA]] are bundled with the starter kit under the directory [[file:elpa-to-submit/][elpa-to-submit/]]. The understanding is that these are bundled just because nobody's gotten around to turning them into packages, and the bundling of them is temporary. For these libraries, autoloads will be generated and kept in the [[file:loaddefs.el][loaddefs.el]] file. This allows them to be loaded on demand rather than at startup. Additionally any emacs-lisp packages located under the [[file:src/][src/]] directory will be added to the load-path. There are also a few files that are meant for code that doesn't belong in the Starter Kit, they are described below in [[* customization][Customization]]. ** Customization :PROPERTIES: :CUSTOM_ID: customization :END: The many defaults built into the starter kit are only the beginning of most users customization of Emacs to suite their needs. The starter kit provides a number of places for additional user and system specific customization. These are designed in such a way that it will be easy for you to continue tracking your own personal customization inside the starter-kit while retaining your ability to pull down general starter-kit updates without conflict. - =git branch= :: The first step to user-specific customization is (like in any git project) to MAKE A BRANCH FOR YOUR LOCAL CHANGES. Save the master branch for pulling down new versions of the starter kit, and save all of your personal information in a personal branch. That way you never have to worry about accidentally =git push='ing up a patch with all of your gnus email passwords. - User specific config :: Your personal configuration information can be stored in a user-specific-config file. This is the file named after your user with the extensions =.el= or =.org= [2]. If you're unsure of your user name evaluate the following code block to find out. #+begin_src sh echo $USER #+end_src If your configuration starts to feel cramped in a single file (although with the nested headlines of an Org-mode file, that could take a while) and you want to stretch your config's legs, you can also create a directory named after your system user name. If a such a directory exists, it will be added to the load-path, and any elisp or org-mode w/embedded elisp files in it will be loaded. - System specific config :: Finally, you may want to configure different settings for different machines. The Starter Kit will look for a file named after the current hostname ending in =.el= or =.org= which will allow host-specific configuration. If you're unsure of your hostname the following can be executed to find out. #+begin_src sh hostname #+end_src - Installing more elisp libraries :: While the starter kit include many useful Emacs lisp libraries, you are bound to find more that you will want to install. The easiest way to install new libraries is through the Emacs Lisp Package Archive (see [[* elpa][ELPA]]). When a library is not available through ELPA you can grab it's source and place it directly in the =src= directory. Any packages found there will automatically be added to your load-path when Emacs starts up, and are guaranteed not to conflict with future starter-kit updates. Some additional miscellaneous configuration and getting started suggestions - First off see the [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Customization.html#Customization][Customization]] node in the Emacs manual. Available online or through the =info= command (run with =C-h i=). - =grep='ing through the =starter-kit-*= files in this directory can provide useful examples for how to do things like install major modes, define keybindings, etc.. - read the following [[http://www.gnu.org/software/emacs/elisp/html_node/Key-Binding-Conventions.html][Key-Binding-Conventions]] before defining too many personal key bindings - The starter-kit comes pre-bundled with a variety of color themes. See [[file:starter-kit-misc.org::*Color%20Themes][Color Themes]] for instructions on how to change the colors used by Emacs. ** Emacs Lisp Package Archive :PROPERTIES: :CUSTOM_ID: elpa :END: Libraries from [[http://tromey.com/elpa][ELPA]] are preferred when available since dependencies are handled automatically, and the burden to update them is removed from the user. In the long term, ideally everything would be installed via ELPA, and only [[file:package.el][package.el]] would need to be distributed with the starter kit. (Or better yet, [[file:package.el][package.el]] would come with Emacs...) See [[* Starter Kit ELPA][Starter Kit ELPA]] for a list of libraries that are pending submission to ELPA. Packages get installed in the [[file:elpa/][elpa/]] directory. There's no vendor/ directory in the starter kit because if an external library is useful enough to be bundled with the starter kit, it should be useful enough to submit to ELPA so that everyone can use it, not just users of the starter kit. However any packages included in the [[file:src][src/]] directory will be added to the load-path, for tracking bleeding edge packages. Sometimes packages are removed from the Starter Kit as they get added to ELPA itself. This has occasionally caused problems with certain packages. If you run into problems with such a package, try removing everything from inside the elpa/ directory and invoking M-x starter-kit-elpa-install in a fresh instance. ** Contributing :PROPERTIES: :CUSTOM_ID: contributing :END: If you know your way around Emacs, please try out the starter kit as a replacement for your regular dotfiles for a while. If there's anything you just can't live without, add it or let me know so I can add it. Take a look at what happens in [[file:init.el][init.el]] to get started. Also: see the [[* Tasks][Tasks section]] in this document. Helping submit new libraries to ELPA is the easiest way to help out. There are two ways you can do this: either take new libraries and make them ready for ELPA, dropping them in the elpa-to-submit directory or take files that are already in elpa-to-submit, ensuring all their dependencies are correctly loaded into ELPA, and sending them to the ELPA maintainer. There are details at http://tromey.com/elpa/upload.html for how ELPA submission works. Grep the project for TODO for other things. Files are licensed under the same license as Emacs unless otherwise specified. See the file COPYING for details. The latest version is at http://github.com/technomancy/emacs-starter-kit/ On Unix, =/home/$USER/.emacs.d=, on windows =Documents and Settings/%your user name%/Application Data= * Implementation :PROPERTIES: :CUSTOM_ID: implementation :END: This section contains all code implementing the Emacs Starter Kit. ** Starter kit basics *** Load path etc. #+srcname: starter-kit-load-paths #+begin_src emacs-lisp (setq dotfiles-dir (file-name-directory (or load-file-name (buffer-file-name)))) (add-to-list 'load-path dotfiles-dir) (add-to-list 'load-path (concat dotfiles-dir "/elpa-to-submit")) (add-to-list 'load-path (concat dotfiles-dir "/elpa-to-submit/jabber")) (setq autoload-file (concat dotfiles-dir "loaddefs.el")) (setq package-user-dir (concat dotfiles-dir "elpa")) (setq custom-file (concat dotfiles-dir "custom.el")) #+end_src *** Ubiquitous Packages These should be loaded on startup rather than autoloaded on demand since they are likely to be used in every session #+srcname: starter-kit-load-on-startup #+begin_src emacs-lisp (require 'cl) (require 'saveplace) (require 'ffap) (require 'uniquify) (require 'ansi-color) (require 'recentf) #+end_src *** Emacs 22 Backport backport some functionality to Emacs 22 if needed #+srcname: starter-kit-emacs-22-helper #+begin_src emacs-lisp (require 'dominating-file) #+end_src *** Function for loading/compiling starter-kit-* #+srcname: starter-kit-load #+begin_src emacs-lisp (defun starter-kit-load (file) "This function is to be used to load starter-kit-*.org files." (org-babel-load-file (expand-file-name file dotfiles-dir))) #+end_src #+source: starter-kit-compile #+begin_src emacs-lisp (defun starter-kit-compile (&optional arg) "Tangle and Byte compile all starter-kit files." (interactive "P") (flet ((age (file) (float-time (time-subtract (current-time) (nth 5 (or (file-attributes (file-truename file)) (file-attributes file))))))) (mapc (lambda (file) (when (string= "org" (file-name-extension file)) (let ((el-file (concat (file-name-sans-extension file) ".el"))) (when (or arg (not (and (file-exists-p el-file) (> (age file) (age el-file))))) (org-babel-tangle-file file el-file "emacs-lisp") (byte-compile-file el-file))))) (apply #'append (mapcar (lambda (d) (when (and (file-exists-p d) (file-directory-p d)) (mapcar (lambda (f) (expand-file-name f d)) (directory-files d)))) (list (concat dotfiles-dir user-login-name) dotfiles-dir)))))) #+end_src *** ELPA (Emacs Lisp Package Manager) Load up [[http://tromey.com/elpa/][ELPA]], the Emacs Lisp package manager #+srcname: starter-kit-elpa #+begin_src emacs-lisp (require 'package) (add-to-list 'package-archives '("original" . "http://tromey.com/elpa/")) (add-to-list 'package-archives '("technomancy" . "http://repo.technomancy.us/emacs/") t) ;; (add-to-list 'package-archives ;; '("marmalade" . "http://marmalade-repo.org/packages/") t) (package-initialize) (starter-kit-load "starter-kit-elpa.org") #+end_src *** Work around OS X bug Work around a bug on OS X where system-name is FQDN #+srcname: starter-kit-osX-workaround #+begin_src emacs-lisp (if (eq system-type 'darwin) (setq system-name (car (split-string system-name "\\.")))) #+end_src *** System/User specific customizations You can keep system- or user-specific customizations here in either raw emacs-lisp files or as embedded elisp in org-mode files (as done in this document). #+srcname: starter-kit-user/system-setup #+begin_src emacs-lisp (setq system-specific-config (concat dotfiles-dir system-name ".el") system-specific-literate-config (concat dotfiles-dir system-name ".org") user-specific-config (concat dotfiles-dir user-login-name ".el") user-specific-literate-config (concat dotfiles-dir user-login-name ".org") user-specific-dir (concat dotfiles-dir user-login-name)) (add-to-list 'load-path user-specific-dir) #+end_src You can keep elisp source in the =src= directory. Packages loaded from here will override those installed by ELPA. This is useful if you want to track the development versions of a project, or if a project is not in elpa. #+srcname: starter-kit-load-elisp-dir #+begin_src emacs-lisp (setq elisp-source-dir (concat dotfiles-dir "src")) (add-to-list 'load-path elisp-source-dir) #+end_src *** Starter kit and Gnus If you would like help setting up the gnus email client, checkout [[file:starter-kit-gnus.org][Starter Kit Gnus]], a starter kit file that is not loaded by default. ** Load the rest of the starter kit core The following files contain the remainder of the core of the Emacs Starter Kit. All of the code in this section should be loaded by everyone using the starter kit. *** Starter kit defuns Starter kit function definitions in [[file:starter-kit-defuns.org][starter-kit-defuns]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-defuns.org") #+end_src *** Starter kit bindings Key Bindings in [[file:starter-kit-bindings.org][starter-kit-bindings]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-bindings.org") #+end_src *** Starter kit misc Miscellaneous settings in [[file:starter-kit-misc.org][starter-kit-misc]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-misc.org") #+end_src *** Starter kit registers Registers for jumping to commonly used files in [[file:starter-kit-registers.org][starter-kit-registers]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-registers.org") #+end_src ** Language/Mode Specific Files These sections pertain to specific languages or modes. Feel free to turn off these sections if you don't plan on using the related mode or language. *** Starter kit yasnippet [[http://code.google.com/p/yasnippet/][yasnippet]] is yet another snippet expansion system for Emacs. It is inspired by TextMate's templating syntax. - watch the [[http://www.youtube.com/watch?v=vOj7btx3ATg][video on YouTube]] - see the [[http://yasnippet.googlecode.com/svn/trunk/doc/index.html][intro and tutorial]] load the yasnippet bundle #+begin_src emacs-lisp (add-to-list 'load-path (expand-file-name "yasnippet" (expand-file-name "src" dotfiles-dir))) (require 'yasnippet) (yas/initialize) #+end_src load the snippets defined in the =./snippets/= directory #+begin_src emacs-lisp (yas/load-directory (expand-file-name "snippets" dotfiles-dir)) #+end_src *** Starter kit Org-mode Located in [[file:starter-kit-org.org][starter-kit-org]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-org.org") #+end_src *** Starter kit eshell Located in [[file:starter-kit-eshell.org][starter-kit-eshell]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-eshell.org") #+end_src *** Starter kit lisp Located in [[file:starter-kit-lisp.org][starter-kit-lisp]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-lisp.org") #+end_src *** Starter kit Haskell Located in [[file:starter-kit-haskell.org][starter-kit-haskell]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-haskell.org") #+end_src *** Starter kit ruby Located in [[file:starter-kit-ruby.org][starter-kit-ruby]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-ruby.org") #+end_src *** Starter kit JS Located in [[file:starter-kit-js.org][starter-kit-js]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-js.org") #+end_src *** Starter Kit Perl Located in [[file:starter-kit-perl.org][starter-kit-perl]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-perl.org") #+end_src *** Starter Kit Python Located in [[file:starter-kit-python.org][starter-kit-python]] #+begin_src emacs-lisp (starter-kit-load "starter-kit-python.org") #+end_src *** Starter Kit Latex Located in [[file:starter-kit-latex.org][starter-kit-latex]] #+begin_src emacs-lisp ;; (starter-kit-load "starter-kit-latex.org") #+end_src ** Load User/System Specific Files *** Settings from M-x customize #+srcname: m-x-customize-customizations #+begin_src emacs-lisp (load custom-file 'noerror) #+end_src *** E-lisp customization After we've loaded all the Starter Kit defaults, lets load the User's stuff. #+srcname: starter-kit-load-files #+begin_src emacs-lisp (if (file-exists-p elisp-source-dir) (let ((default-directory elisp-source-dir)) (normal-top-level-add-subdirs-to-load-path))) (if (file-exists-p system-specific-config) (load system-specific-config)) (if (file-exists-p system-specific-literate-config) (org-babel-load-file system-specific-literate-config)) (if (file-exists-p user-specific-config) (load user-specific-config)) (if (file-exists-p user-specific-literate-config) (org-babel-load-file user-specific-literate-config)) (when (file-exists-p user-specific-dir) (let ((default-directory user-specific-dir)) (mapc #'load (directory-files user-specific-dir nil ".*el$")) (mapc #'org-babel-load-file (directory-files user-specific-dir nil ".*org$")))) #+end_src * FAQ :PROPERTIES: :tangle: no :END: Frequently asked questions. Please share anything that you have come across which you think could be helpful, either in the form of a pull request, a patch, or just an email to me at =schulte.eric= /at/ =gmail.com=. ** How do I use the starter kit without compiling org-mode? :PROPERTIES: :CUSTOM_ID: no-compile :END: Some users wish to run org-mode straight from the sources, since the compiled source can make reading backtraces difficult. Whatever your reason may be, you use the starter kit this way. Skip the =make= step in the [[#installation][Installation]] section. Instead, follow these instructions. 1) =org-install.el= is required by the starter kit. To make it, navigate to the =src/org= directory and enter =make lisp/org-install.el= at the command prompt. 2) Updating the documentation is probably a good idea. Enter =make info=. Optionally, you can update the system-wide org documentation by entering =make install-info=. If you want a PDF version of the manual, you can enter =make doc/org.pdf= and find the resulting file in the doc directory. ** I recently updated the starter kit, but org is an old version. How do I fix this? Doing a =git pull= and =git submodule update= will not be enough. Go to the =src/org= directory and enter =make clean= to get rid of the old version. Then, enter =make=, or follow the [[#no-compile][alternate instructions]]. ** I changed my personal init file, =username.org=, but the starter kit didn't pick up the changes. What do I do now? Some users may find it useful to remove the tangled version of init files. If you find a particular file is not loading as expected, remove the elisp version of that file and restart Emacs. For example, if your $USER is "johndoe", you could issue =rm johndoe.el= to remove the tangled output from the previous time =johndoe.org= was loaded by org-babel. Under no circumstances should you issue =rm *.el=! This will remove the =init.el= file, which is perhaps the most crucial startup file in the starter kit. Use some regexp magic if you want to remove all elisp files except this one. For example, this works nicely: #+begin_src shell-script rm starter-kit*.el #+end_src ** Hey! The org info manual isn't showing up in emacs. What gives? Sometimes, info manuals can be a real headache, but some users prefer them. If the org info manual isn't showing up, or the info manual is displaying the wrong version of the org-mode documentation (Emacs ships with an older version of org-mode than the one the starter kit uses), the problem most likely resides in your local setup. 1) The shell's $INFOPATH variable Have you set the shell's INFOPATH variable? The starter kit should not be ignoring this variable. This variable is copied into the elisp variable =Info-default-directory-list= when emacs starts up. The starter kit then copies =Info-default-directory-list= to =Info-directory-list= without losing any changes you may have made to this variable. This is the next place to look. 2) =Info-directory-list= Is the doc directory for the starter kit version of org-mode at the top of this list? If not, open a ticket and describe what the variable looks like. If you installed the starter kit to =~/.emacs.d/= then the directory =~/.emacs.d/src/org/doc= should be at the top of =Info-directory-list=. 3) Did you =make= the manual? Especially if you choose [[#no-compile][not to compile org-mode]], you may need to compile the documentation. Regardless of whether or not you compiled org, it may be helpful to try this solution out before opening a ticket. Navigate to the =src/org= directory of the starter kit. At the command prompt, type #+begin_src shell-script make info make install-info #+end_src where the last step is optional, and only required if you want to update the site-wide documentation of org-mode. To check if this fixed the issue, first close any Info buffers in emacs and call the Info index with =C-h i= then choose org-mode. * Footnotes [1] If you already have a directory at ~/.emacs.d move it out of the way and put this there instead. [2] The emacs starter kit uses [[http://orgmode.org/worg/org-contrib/babel/][org-babel]] to load embedded elisp code directly from [[http://orgmode.org/][Org Mode]] documents.