From cfb3fbdc9f3550a5848eecb533f7cc6375a89cd3 Mon Sep 17 00:00:00 2001 From: Bozhidar Batsov Date: Wed, 5 Sep 2012 13:41:54 +0300 Subject: [PATCH] unified the README and the project page --- README.md | 204 +++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 185 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index f0c441a..e80ac3a 100644 --- a/README.md +++ b/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,
Bozhidar