unified the README and the project page
This commit is contained in:
Bozhidar Batsov
parent
d8e36b4b74
commit
cfb3fbdc9f
204
README.md
204
README.md
|
|
@ -6,17 +6,19 @@
|
|||
|_| |_| \___|_|\__,_|\__,_|\___|
|
||||
```
|
||||
|
||||
## Prelude
|
||||
|
||||
Emacs is probably the best text editor in the world. However, the
|
||||
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**. **Prelude** has the goal to ease the initial Emacs setup
|
||||
process and to provide you with a much more powerful and productive
|
||||
experience than you get out of the box. By using **Prelude**
|
||||
you're basically getting a "Get me out of the Prelude, I just want to
|
||||
use Emacs" card.
|
||||
**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
|
||||
Prelude** you're basically getting a "Get me out of the Prelude, I
|
||||
just want to use Emacs" card.
|
||||
|
||||
**Prelude** is compatible **ONLY with GNU Emacs 24**.
|
||||
Emacs Prelude is compatible **ONLY with GNU Emacs 24.x**.
|
||||
|
||||
## Fast Forward
|
||||
|
||||
|
|
@ -25,11 +27,10 @@ etc), you already have Emacs 24 installed, as well as `git` & `curl` you
|
|||
can skip the whole manual and just type in your favorite shell the
|
||||
following command:
|
||||
|
||||
`curl -L
|
||||
https://github.com/bbatsov/prelude/raw/master/utils/installer.sh
|
||||
| sh`
|
||||
`curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh`
|
||||
|
||||
You can now power up your Emacs, sit back and enjoy Prelude.
|
||||
You can now power up your Emacs, sit back and enjoy Prelude,
|
||||
forgetting about the rest of this manual.
|
||||
|
||||
There are two environment variables you can use to control the
|
||||
source repository and the installation directory. To change the
|
||||
|
|
@ -52,14 +53,6 @@ Note that the installer will back up any existing `.emacs` file or
|
|||
you're doing a manual install make sure you don't have a `.emacs` file
|
||||
or back up your existing `.emacs.d` directory manually.
|
||||
|
||||
## Would you like to know more?
|
||||
|
||||
Check out the [Prelude's project page](http://batsov.com/prelude) for
|
||||
all the gory details.
|
||||
|
||||
If you're looking for more info on Emacs in general - consult
|
||||
[WikEmacs](http://wikemacs.org).
|
||||
|
||||
## More goodies
|
||||
|
||||
The [Prelude Modules](https://github.com/bbatsov/prelude-modules)
|
||||
|
|
@ -67,6 +60,179 @@ project contains a lot of additional packages for Prelude
|
|||
(install-able via the `package-list-packages` command) - enhanced programming
|
||||
mode configs, latex config, erc config, etc.
|
||||
|
||||
## Installing Emacs 24
|
||||
|
||||
Obviously to use the Emacs Prelude you have to install Emacs 24
|
||||
first. Have a look at the [WikEmacs articles on installing Emacs](http://wikemacs.org/wiki/Installing_Emacs).
|
||||
|
||||
## Installation
|
||||
|
||||
### Automated
|
||||
|
||||
You can install Emacs via the command line with either `curl` or
|
||||
`wget`. Naturally `git` is also required.
|
||||
|
||||
#### Via Curl
|
||||
|
||||
If you're using `curl` type the following command:
|
||||
|
||||
`curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh`
|
||||
|
||||
#### Via Wget
|
||||
|
||||
If you're using `wget` type:
|
||||
|
||||
`wget --no-check-certificate https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O - | sh`
|
||||
|
||||
### Manual
|
||||
|
||||
```bash
|
||||
$ git clone git://github.com/bbatsov/prelude.git path/to/local/repo
|
||||
$ ln -s path/to/local/repo ~/.emacs.d
|
||||
$ cd ~/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.
|
||||
|
||||
## Running
|
||||
|
||||
Nothing fancy here. Just start Emacs as usual. Personally I run Emacs
|
||||
in daemon mode:
|
||||
|
||||
`$ emacs --daemon`
|
||||
|
||||
Afterwards I connect to the server with either a terminal or a GUI
|
||||
client like this:
|
||||
|
||||
```bash
|
||||
$ emacsclient -t
|
||||
$ emacsclient -c
|
||||
```
|
||||
|
||||
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)`.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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.
|
||||
|
||||
[Zenburn](https://github.com/bbatsov/zenburn-emacs) 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).
|
||||
|
||||
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
|
||||
(load-theme 'solarized-dark t)
|
||||
```
|
||||
|
||||
P.S. Solarized is not available by default - you'll have to install it from MELPA first.
|
||||
|
||||
## Personalizing
|
||||
|
||||
Fork the official Prelude repo and add your own touch to it. You're advised to avoid changing stuff outside of the
|
||||
personal folder to avoid having to deal with git merge conflicts in the future.
|
||||
|
||||
## Prelude Modules
|
||||
|
||||
Additional settings for various programming languages are available for installation via MELPA. You might take a look at the [Prelude Modules project](https://github.com/bbatsov/prelude-modules) for further info.
|
||||
|
||||
## Caveats & Pitfalls
|
||||
|
||||
### Problems with flyspell-mode
|
||||
|
||||
Prelude makes heavy use of the flyspell-mode package for spell
|
||||
checking of various things. The proper operation of flyspell depends
|
||||
on the presence of the `aspell` program and an `en` dictionary on your
|
||||
system. You can install `aspell` and the dictionary on OS X with
|
||||
`homebrew` like this:
|
||||
|
||||
```bash
|
||||
$ brew install aspell --lang=en
|
||||
```
|
||||
|
||||
On Linux distros - just use your distro's package manager.
|
||||
|
||||
### 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.
|
||||
|
||||
### MELPA error on initial startup
|
||||
|
||||
If you get some http connection error related to the MELPA 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 (and keys like page up, page down, etc) - to prevent you from being tempted to
|
||||
use them.
|
||||
|
||||
If you'd still like to use the arrow keys just invoke `M-x
|
||||
guru-mode` to enable them for the duration of your
|
||||
current Emacs session or add `(guru-mode -1)` to your
|
||||
personal Emacs customization to enable them permanently.
|
||||
|
||||
### Windows compatibility
|
||||
|
||||
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
|
||||
time. This situation will probably improve over time.
|
||||
|
||||
## Share the knowledge
|
||||
|
||||
[WikEmacs](http://wikemacs.org) collects useful resources for working
|
||||
with GNU Emacs. Please, take the time to peruse and improve them as
|
||||
you accumulate knowledge about Emacs. Prelude makes this especially
|
||||
easy, since it bundles
|
||||
[MediaWiki support](http://wikemacs.org/wiki/Mediawiki.el) + the
|
||||
settings required to access WikEmacs right away.
|
||||
|
||||
## Known issues
|
||||
|
||||
Check out the project's
|
||||
|
|
@ -82,7 +248,7 @@ development of Emacs Prelude.
|
|||
## Bugs & Improvements
|
||||
|
||||
Bug reports and suggestions for improvements are always
|
||||
welcome. GitHub pull requests are even better! :-)
|
||||
welcome. github pull requests are even better! :-)
|
||||
|
||||
Cheers,<br>
|
||||
Bozhidar
|
||||
|
|
|
|||
Loading…
Reference in a new issue