emacs-prelude/README.md

372 lines
12 KiB
Markdown
Raw Normal View History

2012-03-07 17:58:28 +02:00
```
_____ ____ _ _
| ____|_ __ ___ __ _ ___ ___ | _ \ _ __ ___| |_ _ __| | ___
| _| | '_ ` _ \ / _` |/ __/ __| | |_) | '__/ _ \ | | | |/ _` |/ _ \
| |___| | | | | | (_| | (__\__ \ | __/| | | __/ | |_| | (_| | __/
|_____|_| |_| |_|\__,_|\___|___/ |_| |_| \___|_|\__,_|\__,_|\___|
```
2011-10-08 00:55:49 +03:00
## Prelude
2011-10-09 22:26:20 +03:00
Emacs is probably the best text editor in the world. However, the
2011-10-08 00:55:49 +03:00
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 powerful and
productive experience than that you get out of the box. By using **Emacs
2011-10-08 00:55:49 +03:00
Prelude** you're basically getting a "Get me out of the Prelude, I
just want to use Emacs" card.
Emacs Prelude is compatible **ONLY with GNU Emacs 24**. While Emacs 24
is not yet officially released it's a rock solid piece of software
more than suitable for everyday work. There is no good excuse not to
use Emacs 24!
2012-02-17 15:07:54 +02:00
## Fast Forward
2012-02-24 15:22:39 +02:00
Assuming you're using an Unix-like OS (`*BSD`, `GNU/Linux`, `OS X`, `Solaris`,
2012-02-17 15:14:32 +02:00
etc), you already have Emacs 24 installed, as well as `git` & `curl` you
2012-02-17 15:07:54 +02:00
can skip the whole manual and just type in your favorite shell the
following command:
2012-02-17 15:14:32 +02:00
`curl -L
https://github.com/bbatsov/emacs-prelude/raw/master/utils/installer.sh
| sh`
You can now power up your Emacs, sit back and enjoy Prelude,
forgetting about the rest of this manual.
2012-02-17 15:07:54 +02:00
## Getting Emacs 24
2011-10-08 00:55:49 +03:00
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
2012-02-27 12:20:54 +02:00
recommendation would be to get the latest pretest from
[here](http://emacsformacosx.com/builds).
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:
2012-02-24 15:22:39 +02:00
```bash
$ 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
2012-01-26 19:32:26 +02:00
start Emacs in daemon mode (`emacs --daemon`), so that I could share a
single Emacs instance between several Emacs clients (`emacsclient
-c/t`).
2012-02-24 15:22:39 +02:00
Chances are good you have an older version of Emacs installed by
default with OS X. I suggest you to remove that older Emacs version to
avoid conflicts with the new one. Do this:
```bash
$ sudo rm /usr/bin/emacs
$ sudo rm -rf /usr/share/emacs
```
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.
2012-02-27 12:20:54 +02:00
Debian users should look no further than the amazing
[emacs-snapshot APT repo](http://emacs.naquadah.org/). You'll find
2012-02-27 12:20:54 +02:00
installation instructions there for all the relevant Debian
2012-02-24 15:22:39 +02:00
versions out there. High quality, highly recommended builds! After
you've added the repo you can install Emacs 24 with the following
command:
```bash
$ sudo apt-get install emacs-snapshot
```
2012-02-27 12:20:54 +02:00
Ubuntu users have easy access to Emacs 24 as well:
```bash
$ sudo apt-add-repository ppa:cassou/emacs
$ sudo apt-get install emacs-snapshot
```
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
2011-10-08 00:55:49 +03:00
2012-02-17 15:07:54 +02:00
* [Clojure](https://github.com/technomancy/clojure-mode)
* [CoffeeScript](https://github.com/defunkt/coffee-mode)
* [Erlang](http://www.erlang.org/doc/apps/tools/erlang_mode_chapter.html)
* [Groovy](http://groovy.codehaus.org/Emacs+Groovy+Mode)
* [Haskell](http://www.haskell.org/haskellwiki/Haskell_mode_for_Emacs)
2011-10-08 00:55:49 +03:00
### Additional markup languages support
2011-10-08 00:55:49 +03:00
* Markdown
* Sass
* Haml
* Yaml
* LaTeX
### Enhanced configuration
* C
2012-01-26 19:32:26 +02:00
* Clojure
* CoffeeScript
* Common Lisp
2012-01-26 19:32:26 +02:00
* ERC
* JavaScript
* Python
* Ruby
* Scheme
2012-01-26 19:32:26 +02:00
* XML
## Enhanced productivity
2012-02-17 15:07:54 +02:00
* [Projectile](https://github.com/bbatsov/projectile)
2012-01-26 19:32:26 +02:00
* yasnippet
## Bundled packages
* auctex (LaTeX editing)
* clojure-mode
* coffee-mode
* deft (note taking)
* gist (snippet sharing on github.com)
2012-01-26 19:32:26 +02:00
* groovy-mode
2012-02-17 18:32:55 +02:00
* expand-region
* haml-mode
* haskell-mode
* magit (enhanced git integration)
* markdown-mode
* paredit
* projectile (project management mode)
2012-01-26 19:32:26 +02:00
* python.el (improved Python mode)
* sass-mode
* scss-mode
* yaml-mode
* yari (ri frontend)
* yasnippet
2011-10-08 00:55:49 +03:00
## Installation
2012-02-16 16:25:18 +02:00
### Automated
2012-02-17 18:32:55 +02:00
You can install Emacs via the command line with either `curl` or
`wget`. Naturally `git` is also required.
2012-02-16 16:25:18 +02:00
2012-02-24 15:22:39 +02:00
#### Via Curl
2012-02-16 16:25:18 +02:00
If you're using `curl` type the following command:
`curl -L https://github.com/bbatsov/emacs-prelude/raw/master/utils/installer.sh | sh`
2012-02-24 15:22:39 +02:00
#### Via Wget
2012-02-16 16:25:18 +02:00
If you're using `wget` type:
`wget --no-check-certificate https://github.com/bbatsov/emacs-prelude/raw/master/utils/installer.sh -O - | sh`
### Manual
2012-01-26 19:32:26 +02:00
```bash
$ git clone git://github.com/bbatsov/emacs-prelude.git path/to/local/repo
$ ln -s path/to/local/repo ~/.emacs.d
```
You'd do well to replace `~/.emacs.d` with the value of
`user-emacs-directory` for your OS. You can check the value by doing
`C-h v user-emacs-directory` inside Emacs.
2011-10-08 00:55:49 +03:00
2011-12-12 15:52:42 +02:00
You might have to install the `make` and `makeinfo` packages if you
don't have them already, since the build of some packages obtained via
`el-get` might require them.
2011-10-08 00:55:49 +03:00
## Running
Nothing fancy here. Just start Emacs as usual. Personally I run Emacs
in daemon mode:
2012-01-26 19:32:26 +02:00
`$ emacs --daemon`
2011-10-08 00:55:49 +03:00
Afterwards I connect to the server with either a terminal or a GUI
client like this:
2012-01-26 19:32:26 +02:00
```bash
$ emacsclient -t
$ emacsclient -c
```
2012-02-17 15:07:54 +02:00
You'd probably do well to put a few aliases in your `.zshrc` (or
`.bashrc`):
```bash
alias e=emacsclient -t
alias ec=emacsclient -c
alias vim=emacsclient -t
alias vi=emacsclient -t
```
The last two aliases are helpful if you're used to editing files from
the command line using `vi(m)`.
2012-02-24 15:22:39 +02:00
## Getting to know Prelude
Certainly the best way to understand how Prelude enhances the default
Emacs experience is to peruse Prelude's source code (which is
obviously written in Emacs Lisp). If you're intimidated by the source
- do not despair. Prelude includes a `prelude-mode` minor Emacs mode
which collects some of the additional functionality added by
Prelude. It also adds an additional keymap that binds many of those
extensions to keybindings.
2012-01-26 19:32:26 +02:00
## Color Themes
Emacs 24 ships with a new theming facility that effectively renders
the old color-theme package obsolete. Emacs 24 provides a dozen of
built-in themes you can use out-of-the-box by invoking the `M-x
load-theme` command. Emacs Prelude adds two more popular themes to the
2012-02-24 15:22:39 +02:00
mix - [Zenburn](https://github.com/bbatsov/zenburn-emacs) and
[Solarized](https://github.com/bbatsov/solarized-emacs) (I'm the
maintainer of the Emacs ports included).
2012-01-26 19:32:26 +02:00
Zenburn is the default color theme in Prelude, but you can change it
at your discretion. Why Zenburn? I (and lots of hackers around the
world) find it pretty neat for some reason. Personally 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).
2011-10-08 00:55:49 +03:00
2012-02-17 15:07:54 +02:00
To disable Zenburn just put in your personal config the following
line:
```elisp
(disable-theme 'zenburn)
```
Or you can use another theme altogether by adding something like:
```elisp
2012-03-07 17:50:47 +02:00
(load-theme 'solarized-dark t)
2012-02-17 15:07:54 +02:00
```
## 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
2012-01-26 19:32:26 +02:00
under the **personal** directory in `prelude-dir`. They will be loaded
automatically be Prelude on startup.
2012-02-24 15:22:39 +02:00
Avoid modifying the Prelude config itself (unless you're not
2012-02-27 12:20:54 +02:00
intimidated to maintain a personal fork on GitHub) - this will make it
2012-02-24 15:22:39 +02:00
hard for you to receive automatic updates in the future.
2011-12-12 15:52:42 +02:00
## Caveats & Pitfalls
2012-02-27 12:20:54 +02:00
### Ugly colors in the terminal Emacs version
If your Emacs looks considerably uglier in a terminal (compared to the
GUI version) try adding this to your `.bashrc` or `.zshrc`:
```bash
export TERM=xterm-256color
```
Source the `.bashrc` file and start Emacs again.
2012-02-17 18:32:55 +02:00
### Marmalade error on initial startup
If you get some http connection error related to the Marmalade repo
just do a manual `M-x package-refresh-contents` and restart Emacs
afterwards.
### 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.
If you'd still like to use the arrow keys just invoke `M-x
prelude-restore-arrow-keys` to enable them for the duration of your
current Emacs session or add `(prelude-restore-arrow-keys)` to your
personal Emacs customization to enable them permanently.
2012-01-26 19:32:26 +02:00
### Windows compatibility
2012-02-24 15:22:39 +02:00
While everything in Prelude should work fine in Windows, I test it only
with Linux & OSX, so there are Windows related problems from time to
2012-01-26 19:32:26 +02:00
time. This situation will probably improve over time.
2011-10-08 00:55:49 +03:00
## Known issues
2012-02-27 12:20:54 +02:00
Check out the project's
[issue list](https://github.com/bbatsov/emacs-prelude/issues?sort=created&direction=desc&state=open)
a list of unresolved issues. By the way - feel free to fix any of them
and sent me a pull request. :-)
2012-02-17 15:07:54 +02:00
## Contributors
Here's a [list](https://github.com/bbatsov/emacs-prelude/contributors) of all the people who have contributed to the
development of Emacs Prelude.
2011-10-08 00:55:49 +03:00
## Bugs & Improvements
Bug reports and suggestions for improvements are always
2012-01-26 19:32:26 +02:00
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.
2011-10-08 00:55:49 +03:00
2012-02-24 15:22:39 +02:00
Cheers,<br>
2011-10-08 00:55:49 +03:00
Bozhidar