jt/emacs-prelude
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

another bunch of README fixes

Browse source
This commit is contained in:
Bozhidar Batsov 2012-09-16 14:52:48 +03:00
parent 7e83806cd2
commit b3d87a42f5
1 changed files with 56 additions and 72 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

128
README.md
View file

@ -1,26 +1,19 @@
``` Emacs Prelude
____ _ _ =============
| _ \ _ __ ___| |_ _ __| | ___
| |_) | '__/ _ \ | | | |/ _` |/ _ \
| __/| | | __/ | |_| | (_| | __/
|_| |_| \___|_|\__,_|\__,_|\___|
```
# Prelude
Emacs is probably the best text editor in the world. However, the Emacs is probably the best text editor in the world. However, the
process of coming up with a useful Emacs configuration is long and process of coming up with a useful Emacs configuration is long and
difficult. It's this process that separates you from truly taking 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 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 **Prelude**. **Emacs Prelude** has the goal to ease the initial Emacs
Emacs setup process and to provide you with a much more powerful and 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 productive experience than the one you get out of the box. By using
Prelude** you're basically getting a "Get me out of the Prelude, I **Emacs Prelude** you're basically getting a *"Get me out of the
just want to use Emacs" card. Prelude, I just want to use Emacs"* card.
Emacs Prelude is compatible **ONLY with GNU Emacs 24.x**. Emacs Prelude is compatible **ONLY with GNU Emacs 24.x**.
# Fast Forward ## Fast Forward
Assuming you're using an Unix-like OS (`*BSD`, `GNU/Linux`, `OS X`, `Solaris`, Assuming you're using an Unix-like OS (`*BSD`, `GNU/Linux`, `OS X`, `Solaris`,
etc), you already have Emacs 24 installed, as well as `git` & `curl` you etc), you already have Emacs 24 installed, as well as `git` & `curl` you
@ -39,19 +32,13 @@ source repository and the installation directory. To change the
installation directory: installation directory:
```bash ```bash
$ PRELUDE_INSTALL_DIR="$HOME/.emacs.d" && $ PRELUDE_INSTALL_DIR="$HOME/.emacs.d" && 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
``` ```
To change the source repository: To change the source repository:
```bash ```bash
$ PRELUDE_URL="https://github.com/yourname/prelude.git" && $ PRELUDE_URL="https://github.com/yourname/prelude.git" && 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
``` ```
Note that the installer will back up any existing `.emacs` file or Note that the installer will back up any existing `.emacs` file or
@ -59,45 +46,42 @@ 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 you're doing a manual install make sure you don't have a `.emacs` file
or back up your existing `.emacs.d` directory manually. or back up your existing `.emacs.d` directory manually.
# More goodies ## More goodies
The [Prelude Modules](https://github.com/bbatsov/prelude-modules) The [Prelude Modules](https://github.com/bbatsov/prelude-modules)
project contains a lot of additional packages for Prelude project contains a lot of additional packages for Prelude
(install-able via the `package-list-packages` command) - enhanced programming (install-able via the `package-list-packages` command) - enhanced programming
mode configs, latex config, erc config, etc. mode configs, latex config, erc config, etc.
# Installing Emacs 24 ## Installing Emacs 24
Obviously to use the Emacs Prelude you have to install 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). first. Have a look at the [WikEmacs articles on installing Emacs](http://wikemacs.org/wiki/Installing_Emacs).
# Installation ## Installation
## Automated ### Automated
You can install Emacs via the command line with either `curl` or You can install Emacs via the command line with either `curl` or
`wget`. Naturally `git` is also required. `wget`. Naturally `git` is also required.
### Via Curl #### Via Curl
If you're using `curl` type the following command: If you're using `curl` type the following command:
```bash ```bash
$ curl -L $ curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
``` ```
### Via Wget #### Via Wget
If you're using `wget` type: If you're using `wget` type:
```bash ```bash
$ wget --no-check-certificate $ wget --no-check-certificate https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O - | sh
https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O -
| sh
``` ```
## Manual ### Manual
```bash ```bash
$ git clone git://github.com/bbatsov/prelude.git path/to/local/repo $ git clone git://github.com/bbatsov/prelude.git path/to/local/repo
@ -109,7 +93,7 @@ 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 `user-emacs-directory` for your OS. You can check the value by doing
`C-h v user-emacs-directory` inside Emacs. `C-h v user-emacs-directory` inside Emacs.
# Running ## Running
Nothing fancy here. Just start Emacs as usual. Personally I run Emacs Nothing fancy here. Just start Emacs as usual. Personally I run Emacs
in daemon mode: in daemon mode:
@ -139,17 +123,17 @@ alias vi=emacsclient -t
The last two aliases are helpful if you're used to editing files from The last two aliases are helpful if you're used to editing files from
the command line using `vi(m)`. the command line using `vi(m)`.
# Getting to know Prelude ## Getting to know Prelude
Certainly the best way to understand how Prelude enhances the default Certainly the best way to understand how Prelude enhances the default
Emacs experience is to peruse Prelude's source code (which is Emacs experience is to peruse Prelude's source code (which is
obviously written in Emacs Lisp). If you're intimidated by the source obviously written in Emacs Lisp). Understanding the code is not
- do not despair. Prelude includes a `prelude-mode` minor Emacs mode necessary of course. Prelude includes a `prelude-mode` minor Emacs mode
which collects some of the additional functionality added by which collects some of the additional functionality added by
Prelude. It also adds an additional keymap that binds many of those Prelude. It also adds an additional keymap that binds many of those
extensions to keybindings. extensions to keybindings.
## Automatic package installation ### Automatic package installation
The default Prelude installation comes with a bare minimum of The default Prelude installation comes with a bare minimum of
functionality. It will however install add-ons for various programming functionality. It will however install add-ons for various programming
@ -159,7 +143,7 @@ configuration will be installed automatically for you.
You can, of course, install anything you wish manually as well. You can, of course, install anything you wish manually as well.
## Color Themes ### Color Themes
Emacs 24 ships with a new theming facility that effectively renders Emacs 24 ships with a new theming facility that effectively renders
the old color-theme package obsolete. Emacs 24 provides a dozen of the old color-theme package obsolete. Emacs 24 provides a dozen of
@ -188,18 +172,37 @@ Or you can use another theme altogether by adding something like:
P.S. Solarized is not available by default - you'll have to install it from MELPA first. P.S. Solarized is not available by default - you'll have to install it from MELPA first.
## Personalizing ### Personalizing
Fork the official Prelude repo and add your own touch to it. You're advised to avoid changing stuff outside of the 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. personal folder to avoid having to deal with git merge conflicts in the future.
## Prelude Modules #### Disable whitespace-mode
Some people find `whitespace-mode` too intrusive and might want to
disable it. It come be done from your personal config with the
following bit of code:
```lisp
(add-hook 'prog-mode-hook 'prelude-turn-off-whitespace t)
```
#### Disable flyspell-mode
If you're not fond of spellchecking on the fly:
```lisp
(add-hook 'text-mode-hook 'turn-off-flyspell t)
(add-hook 'prog-mode-hook 'turn-off-flyspell t)
```
### 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. 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 ## Caveats & Pitfalls
## Problems with flyspell-mode ### Problems with flyspell-mode
Prelude makes heavy use of the flyspell-mode package for spell Prelude makes heavy use of the flyspell-mode package for spell
checking of various things. The proper operation of flyspell depends checking of various things. The proper operation of flyspell depends
@ -213,7 +216,7 @@ $ brew install aspell --lang=en
On Linux distros - just use your distro's package manager. On Linux distros - just use your distro's package manager.
## Ugly colors in the terminal Emacs version ### Ugly colors in the terminal Emacs version
If your Emacs looks considerably uglier in a terminal (compared to the If your Emacs looks considerably uglier in a terminal (compared to the
GUI version) try adding this to your `.bashrc` or `.zshrc`: GUI version) try adding this to your `.bashrc` or `.zshrc`:
@ -224,13 +227,13 @@ $ export TERM=xterm-256color
Source the `.bashrc` file and start Emacs again. Source the `.bashrc` file and start Emacs again.
## MELPA error on initial startup ### MELPA error on initial startup
If you get some http connection error related to the MELPA repo If you get some http connection error related to the MELPA repo
just do a manual `M-x package-refresh-contents` and restart Emacs just do a manual `M-x package-refresh-contents` and restart Emacs
afterwards. afterwards.
## No arrow navigation in editor buffers ### No arrow navigation in editor buffers
This is not a bug - it's a feature! I firmly believe that the one true 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 way to use Emacs is by using it the way it was intended to be used (as
@ -247,32 +250,13 @@ personal Emacs customization to enable them permanently:
(add-hook 'prog-mode-hook 'turn-off-guru-mode t) (add-hook 'prog-mode-hook 'turn-off-guru-mode t)
``` ```
## Disable whitespace-mode ### Windows compatibility
Some people find `whitespace-mode` too intrusive and might want to
disable it. It come be done from your personal config with the
following bit of code:
```lisp
(add-hook 'prog-mode-hook 'prelude-turn-off-whitespace t)
```
## Disable flyspell-mode
If you're not fond of spellchecking on the fly:
```lisp
(add-hook 'text-mode-hook 'turn-off-flyspell t)
(add-hook 'prog-mode-hook 'turn-off-flyspell t)
```
## Windows compatibility
While everything in Prelude should work fine in Windows, I test it only 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 with Linux & OSX, so there are Windows related problems from time to
time. This situation will probably improve over time. time. This situation will probably improve over time.
# Share the knowledge ## Share the knowledge
[WikEmacs](http://wikemacs.org) collects useful resources for working [WikEmacs](http://wikemacs.org) collects useful resources for working
with GNU Emacs. Please, take the time to peruse and improve them as with GNU Emacs. Please, take the time to peruse and improve them as
@ -281,19 +265,19 @@ easy, since it bundles
[MediaWiki support](http://wikemacs.org/wiki/Mediawiki.el) + the [MediaWiki support](http://wikemacs.org/wiki/Mediawiki.el) + the
settings required to access WikEmacs right away. settings required to access WikEmacs right away.
# Known issues ## Known issues
Check out the project's Check out the project's
[issue list](https://github.com/bbatsov/prelude/issues?sort=created&direction=desc&state=open) [issue list](https://github.com/bbatsov/prelude/issues?sort=created&direction=desc&state=open)
a list of unresolved issues. By the way - feel free to fix any of them a list of unresolved issues. By the way - feel free to fix any of them
and send me a pull request. :-) and send me a pull request. :-)
# Contributors ## Contributors
Here's a [list](https://github.com/bbatsov/prelude/contributors) of all the people who have contributed to the Here's a [list](https://github.com/bbatsov/prelude/contributors) of all the people who have contributed to the
development of Emacs Prelude. development of Emacs Prelude.
# Bugs & Improvements ## Bugs & Improvements
Bug reports and suggestions for improvements are always Bug reports and suggestions for improvements are always
welcome. GitHub pull requests are even better! :-) welcome. GitHub pull requests are even better! :-)