Restructure the README into a manual
This commit is contained in:
Bozhidar Batsov
parent
63c697c2f4
commit
4490d51798
17 changed files with 789 additions and 684 deletions
669
README.md
669
README.md
|
|
@ -25,52 +25,6 @@ You can support the development of Prelude via
|
||||||
[](https://liberapay.com/bbatsov/donate)
|
[](https://liberapay.com/bbatsov/donate)
|
||||||
[](https://www.patreon.com/bbatsov)
|
[](https://www.patreon.com/bbatsov)
|
||||||
|
|
||||||
**Table of Contents**
|
|
||||||
|
|
||||||
- [Fast Forward](#fast-forward)
|
|
||||||
- [Installing Emacs](#installing-emacs)
|
|
||||||
- [Installation](#installation)
|
|
||||||
- [Automated](#automated)
|
|
||||||
- [Via Curl](#via-curl)
|
|
||||||
- [Via Wget](#via-wget)
|
|
||||||
- [Manual](#manual)
|
|
||||||
- [Updating Prelude](#updating-prelude)
|
|
||||||
- [Manual update](#manual-update)
|
|
||||||
- [Update all bundled packages](#update-all-bundled-packages)
|
|
||||||
- [Update Prelude's code](#update-preludes-code)
|
|
||||||
- [Restart Prelude](#restart-prelude)
|
|
||||||
- [Automatic update](#automatic-update)
|
|
||||||
- [Enabling additional modules](#enabling-additional-modules)
|
|
||||||
- [Running](#running)
|
|
||||||
- [Getting to know Prelude](#getting-to-know-prelude)
|
|
||||||
- [Keymap](#keymap)
|
|
||||||
- [Global](#global)
|
|
||||||
- [Prelude Mode](#prelude-mode)
|
|
||||||
- [macOS modifier keys](#macos-modifier-keys)
|
|
||||||
- [Projectile](#projectile)
|
|
||||||
- [Helm](#helm)
|
|
||||||
- [Key-chords](#key-chords)
|
|
||||||
- [Disabling key-chords](#disabling-key-chords)
|
|
||||||
- [Cheatsheet](#cheatsheet)
|
|
||||||
- [Automatic package installation](#automatic-package-installation)
|
|
||||||
- [Color Themes](#color-themes)
|
|
||||||
- [Personalizing](#personalizing)
|
|
||||||
- [Disabling whitespace-mode](#disabling-whitespace-mode)
|
|
||||||
- [Disable flyspell-mode](#disable-flyspell-mode)
|
|
||||||
- [Caveats & Pitfalls](#caveats--pitfalls)
|
|
||||||
- [Updating bundled packages](#updating-bundled-packages)
|
|
||||||
- [Problems with flyspell-mode](#problems-with-flyspell-mode)
|
|
||||||
- [Ugly colors in the terminal Emacs version](#ugly-colors-in-the-terminal-emacs-version)
|
|
||||||
- [MELPA error on initial startup](#melpa-error-on-initial-startup)
|
|
||||||
- [Warnings on arrow navigation in editor buffers](#warnings-on-arrow-navigation-in-editor-buffers)
|
|
||||||
- [Customized C-a behavior](#customized-c-a-behavior)
|
|
||||||
- [Poor ido matching performance on large datasets](#poor-ido-matching-performance-on-large-datasets)
|
|
||||||
- [Windows compatibility](#windows-compatibility)
|
|
||||||
- [Known issues](#known-issues)
|
|
||||||
- [Support](#support)
|
|
||||||
- [Contributors](#contributors)
|
|
||||||
- [Bugs & Improvements](#bugs--improvements)
|
|
||||||
|
|
||||||
## Fast Forward
|
## Fast Forward
|
||||||
|
|
||||||
Assuming you're using an Unix-like OS (`*BSD`, `GNU/Linux`, `macOS`, `Solaris`,
|
Assuming you're using an Unix-like OS (`*BSD`, `GNU/Linux`, `macOS`, `Solaris`,
|
||||||
|
|
@ -108,629 +62,6 @@ Don't forget to adjust your `prelude-modules.el` file in your personal directory
|
||||||
once the installation is done. By default most of the modules
|
once the installation is done. By default most of the modules
|
||||||
that ship with Prelude are not loaded.
|
that ship with Prelude are not loaded.
|
||||||
|
|
||||||
## Installing Emacs
|
|
||||||
|
|
||||||
Obviously to use the Emacs Prelude you have to install Emacs
|
|
||||||
first. Have a look at
|
|
||||||
the
|
|
||||||
[WikEmacs articles on installing Emacs](http://wikemacs.org/index.php/Installing_Emacs).
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
### Automated
|
|
||||||
|
|
||||||
You can install **Emacs Prelude** 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:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Via Wget
|
|
||||||
|
|
||||||
If you're using `wget` type:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
wget --no-check-certificate https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O - | sh
|
|
||||||
```
|
|
||||||
|
|
||||||
### Manual
|
|
||||||
|
|
||||||
Make sure you do not have any `~/.emacs` file present.
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone git://github.com/bbatsov/prelude.git path/to/local/repo
|
|
||||||
ln -s path/to/local/repo ~/.emacs.d
|
|
||||||
cd ~/.emacs.d
|
|
||||||
```
|
|
||||||
|
|
||||||
If you are using Windows, you should check what Emacs thinks the `~` directory is by running Emacs and typing `C-x d ~/<RET>`, and then adjust the command appropriately.
|
|
||||||
|
|
||||||
## Updating Prelude
|
|
||||||
|
|
||||||
### Manual update
|
|
||||||
|
|
||||||
The update procedure is fairly straightforward and consists of 3 steps:
|
|
||||||
|
|
||||||
#### Update all bundled packages
|
|
||||||
|
|
||||||
Just run <kbd>M-x package-list-packages RET U x</kbd>.
|
|
||||||
|
|
||||||
#### Update Prelude's code
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cd path/to/prelude/installation
|
|
||||||
git pull
|
|
||||||
```
|
|
||||||
|
|
||||||
The `path/to/prelude/installation` is usually `~/.emacs.d` (at least
|
|
||||||
on Unix systems).
|
|
||||||
|
|
||||||
#### Restart Prelude
|
|
||||||
|
|
||||||
It's generally a good idea to stop Emacs after you do the update. The
|
|
||||||
next time Prelude starts it will install any new dependencies (if
|
|
||||||
there are such).
|
|
||||||
|
|
||||||
### Automatic update
|
|
||||||
|
|
||||||
Simply run <kbd>M-x prelude-update</kbd> from Emacs itself and restart Emacs afterwards.
|
|
||||||
|
|
||||||
## Pinning packages
|
|
||||||
|
|
||||||
By default, Prelude will install packages from the melpa and gnu package
|
|
||||||
repositories. Occasionally package integration can break when upgrading packages.
|
|
||||||
This can be avoided by pinning packages to stable versions in other repositories.
|
|
||||||
To do so, copy `prelude-pinned-packages.el` from the sample directory to
|
|
||||||
Prelude's root directory and adjust the [variables](https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html)
|
|
||||||
inside accordingly.
|
|
||||||
|
|
||||||
## Enabling additional modules
|
|
||||||
|
|
||||||
By default most of the modules that ship with Prelude are not loaded. For more information on the functionality provided by these modules visit the [docs](modules/doc/README.md).
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
;;; Uncomment the modules you'd like to use and restart Prelude afterwards
|
|
||||||
|
|
||||||
(require 'prelude-c)
|
|
||||||
;; (require 'prelude-clojure)
|
|
||||||
;; (require 'prelude-coffee)
|
|
||||||
;; (require 'prelude-common-lisp)
|
|
||||||
;; (require 'prelude-css)
|
|
||||||
(require 'prelude-emacs-lisp)
|
|
||||||
(require 'prelude-erc)
|
|
||||||
;; (require 'prelude-erlang)
|
|
||||||
;; (require 'prelude-elixir)
|
|
||||||
;; (require 'prelude-haskell)
|
|
||||||
(require 'prelude-js)
|
|
||||||
;; (require 'prelude-latex)
|
|
||||||
(require 'prelude-lisp)
|
|
||||||
(require 'prelude-org)
|
|
||||||
(require 'prelude-perl)
|
|
||||||
;; (require 'prelude-python)
|
|
||||||
;; (require 'prelude-ruby)
|
|
||||||
;; (require 'prelude-scala)
|
|
||||||
(require 'prelude-scheme)
|
|
||||||
;; (require 'prelude-scss)
|
|
||||||
;; (require 'prelude-web)
|
|
||||||
(require 'prelude-xml)
|
|
||||||
```
|
|
||||||
|
|
||||||
You'll need to adjust your `prelude-modules.el` file once the
|
|
||||||
installation is done. If you are doing a manual install then you first
|
|
||||||
need to copy the `prelude-modules.el` available in the sample
|
|
||||||
directory to the `personal` directory under `path/to/prelude/installation`
|
|
||||||
and then adjust that one.
|
|
||||||
|
|
||||||
After you've uncommented a module you should either restart Emacs or evaluate the module
|
|
||||||
`require` expression with <kbd>C-x C-e</kbd>.
|
|
||||||
|
|
||||||
## Running
|
|
||||||
|
|
||||||
Nothing fancy here. Just start Emacs as usual. Personally I run Emacs
|
|
||||||
in daemon mode:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
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)`.
|
|
||||||
|
|
||||||
You can also open a file with the cursor positioned directly on a specific line:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
emacsclient somefile:1234
|
|
||||||
```
|
|
||||||
|
|
||||||
This will open file 'somefile' and set cursor on line 1234.
|
|
||||||
|
|
||||||
## 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). Understanding the code is not
|
|
||||||
necessary of course. 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.
|
|
||||||
|
|
||||||
### Keymap
|
|
||||||
|
|
||||||
#### Global
|
|
||||||
|
|
||||||
Keybinding | Description
|
|
||||||
-------------------|------------------------------------------------------------
|
|
||||||
<kbd>C-x \\</kbd> | `align-regexp`
|
|
||||||
<kbd>C-+</kbd> | Increase font size(`text-scale-increase`).
|
|
||||||
<kbd>C--</kbd> | Decrease font size(`text-scale-decrease`).
|
|
||||||
<kbd>C-x O</kbd> | Go back to previous window (the inverse of `other-window` (`C-x o`)).
|
|
||||||
<kbd>C-^</kbd> | Join two lines into one(`crux-top-join-line`).
|
|
||||||
<kbd>C-x p</kbd> | Start `proced` (manage processes from Emacs; works only in Linux).
|
|
||||||
<kbd>C-x m</kbd> | Start `eshell`.
|
|
||||||
<kbd>C-x M-m</kbd> | Start your default shell.
|
|
||||||
<kbd>C-x C-m</kbd> | Alias for `M-x`.
|
|
||||||
<kbd>M-X</kbd> | Like `M-x` but limited to commands that are relevant to the active major mode.
|
|
||||||
<kbd>C-h A</kbd> | Run `apropos` (search in all Emacs symbols).
|
|
||||||
<kbd>C-h C-m</kbd> | Display key bindings of current major mode and descriptions of every binding.
|
|
||||||
<kbd>M-/</kbd> | Run `hippie-expand` (a replacement for the default `dabbrev-expand`).
|
|
||||||
<kbd>C-x C-b</kbd> | Open `ibuffer` (a replacement for the default `buffer-list`).
|
|
||||||
<kbd>F11</kbd> | Make the window full screen.
|
|
||||||
<kbd>F12</kbd> | Toggle the Emacs menu bar.
|
|
||||||
<kbd>C-x g</kbd> | Open Magit's status buffer.
|
|
||||||
<kbd>C-x M-g</kbd> | Open Magit's popup of popups.
|
|
||||||
<kbd>M-Z</kbd> | Zap up to char.
|
|
||||||
<kbd>C-=</kbd> | Run `expand-region` (incremental text selection).
|
|
||||||
<kbd>C-a</kbd> | Run `crux-move-beginning-of-line`. Read [this](http://emacsredux.com/blog/2013/05/22/smarter-navigation-to-the-beginning-of-a-line/) for details.
|
|
||||||
|
|
||||||
#### Prelude Mode
|
|
||||||
|
|
||||||
Keybinding | Description
|
|
||||||
-------------------|------------------------------------------------------------
|
|
||||||
<kbd>C-c o</kbd> | Open the currently visited file with an external program.
|
|
||||||
<kbd>C-c i</kbd> | Search for a symbol, only for buffers that contain code
|
|
||||||
<kbd>C-c g</kbd> | Search in Google for the thing under point (or an interactive query).
|
|
||||||
<kbd>C-c G</kbd> | Search in GitHub for the thing under point (or an interactive query).
|
|
||||||
<kbd>C-c y</kbd> | Search in YouTube for the thing under point (or an interactive query).
|
|
||||||
<kbd>C-c U</kbd> | Search in Duckduckgo for the thing under point (or an interactive query).
|
|
||||||
<kbd>C-S-RET</kbd> or <kbd>Super-o</kbd> | Insert an empty line above the current line and indent it properly.
|
|
||||||
<kbd>S-RET</kbd> or <kbd>M-o</kbd> | Insert an empty line and indent it properly (as in most IDEs).
|
|
||||||
<kbd>C-S-up</kbd> or <kbd>M-S-up</kbd> | Move the current line or region up.
|
|
||||||
<kbd>C-S-down</kbd> or <kbd>M-S-down</kbd>| Move the current line or region down.
|
|
||||||
<kbd>C-c n</kbd> | Fix indentation in buffer and strip whitespace.
|
|
||||||
<kbd>C-c f</kbd> | Open recently visited file.
|
|
||||||
<kbd>C-M-\\</kbd> | Indent region (if selected) or the entire buffer.
|
|
||||||
<kbd>C-c u</kbd> | Open a new buffer containing the contents of URL.
|
|
||||||
<kbd>C-c e</kbd> | Eval a bit of Emacs Lisp code and replace it with its result.
|
|
||||||
<kbd>C-c s</kbd> | Swap two active windows.
|
|
||||||
<kbd>C-c D</kbd> | Delete current file and buffer.
|
|
||||||
<kbd>C-c d</kbd> | Duplicate the current line (or region).
|
|
||||||
<kbd>C-c M-d</kbd> | Duplicate and comment the current line (or region).
|
|
||||||
<kbd>C-c r</kbd> | Rename the current buffer and its visiting file if any.
|
|
||||||
<kbd>C-c t</kbd> | Open a terminal emulator (`ansi-term`).
|
|
||||||
<kbd>C-c k</kbd> | Kill all open buffers except the one you're currently in.
|
|
||||||
<kbd>C-c TAB</kbd> | Indent and copy region to clipboard
|
|
||||||
<kbd>C-c I</kbd> | Open user's init file.
|
|
||||||
<kbd>C-c S</kbd> | Open shell's init file.
|
|
||||||
<kbd>C-c . +</kbd> | Increment integer at point. Default is +1.
|
|
||||||
<kbd>C-c . -</kbd> | Decrement integer at point. Default is -1.
|
|
||||||
<kbd>C-c . *</kbd> | Multiply integer at point. Default is *2.
|
|
||||||
<kbd>C-c . /</kbd> | Divide integer at point. Default is /2.
|
|
||||||
<kbd>C-c . \\</kbd> | Modulo integer at point. Default is modulo 2.
|
|
||||||
<kbd>C-c . ^</kbd> | Power to the integer at point. Default is ^2.
|
|
||||||
<kbd>C-c . <</kbd> | Left-shift integer at point. Default is 1 position to the left.
|
|
||||||
<kbd>C-c . ></kbd> | Right-shift integer at point. Default is 1 position to the right.
|
|
||||||
<kbd>C-c . #</kbd> | Convert integer at point to specified base. Default is 10.
|
|
||||||
<kbd>C-c . %</kbd> | Replace integer at point with another specified integer.
|
|
||||||
<kbd>C-c . '</kbd> | Perform arithmetic operations on integer at point. User specifies the operator.
|
|
||||||
<kbd>Super-r</kbd> | Recent files
|
|
||||||
<kbd>Super-j</kbd> | Join lines
|
|
||||||
<kbd>Super-k</kbd> | Kill whole line
|
|
||||||
<kbd>Super-m m</kbd> | Magit status
|
|
||||||
<kbd>Super-m l</kbd> | Magit log
|
|
||||||
<kbd>Super-m f</kbd> | Magit file log
|
|
||||||
<kbd>Super-m b</kbd> | Magit blame mode
|
|
||||||
|
|
||||||
**Note**: For various arithmetic operations, the prefix `C-c .` only needs to be pressed once for the first operation.
|
|
||||||
For subsequent operations, only the appropriate operations (i.e. `+`, `-`, `*`, `/`... needs to be pressed).
|
|
||||||
|
|
||||||
#### macOS modifier keys
|
|
||||||
|
|
||||||
Prelude does not mess by default with the standard mapping of `Command` (to `Super`) and `Option` (to `Meta`).
|
|
||||||
|
|
||||||
If you want to swap them add this to your [personal config](#personalizing):
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq mac-command-modifier 'meta)
|
|
||||||
(setq mac-option-modifier 'super)
|
|
||||||
```
|
|
||||||
|
|
||||||
You can also temporarily swap them with `C-c w` (`M-x prelude-swap-meta-and-super`). Note that some emacs distributions (like [emacs-mac](https://bitbucket.org/mituharu/emacs-mac.git) come with `Command` [set](https://bitbucket.org/mituharu/emacs-mac/src/7fdbfba85d543f01b81e997e2b03788c35cb3bfa/src/macterm.c?at=master&fileviewer=file-view-default#macterm.c-6147:6169) to `Meta`.
|
|
||||||
|
|
||||||
**Note**: I'd highly recommend to all macOS users to consider
|
|
||||||
[remapping Return to
|
|
||||||
Control](http://emacsredux.com/blog/2013/11/12/a-crazy-productivity-boost-remap-return-to-control/)
|
|
||||||
instead. That's an epic productivity boost and it's not as crazy as it sounds!
|
|
||||||
|
|
||||||
#### Projectile
|
|
||||||
|
|
||||||
[Projectile](https://github.com/bbatsov/projectile) is one of the essential packages bundled with Prelude.
|
|
||||||
It provides an easy way to navigate and switch projects. Take a look at its extensive documentation
|
|
||||||
to get a feel for everything you can do with Projectile.
|
|
||||||
|
|
||||||
Prelude adds an extra keymap prefix `s-p` (`s` stands for
|
|
||||||
`Super`) in addition to the standard one `C-c p`. By default on Windows keyboard
|
|
||||||
`Super` is mapped to the `Windows` key and on macOS keyboards `Super` is mapped
|
|
||||||
to the `Command` key.
|
|
||||||
|
|
||||||
If you ever forget any of Projectile's keybindings just do a:
|
|
||||||
|
|
||||||
<kbd>C-c p C-h</kbd> or <kbd>s-p C-h</kbd>
|
|
||||||
|
|
||||||
Alternatively you can just press <kbd>s-p</kbd> and wait for a moment
|
|
||||||
for `which-key` to kick in and show you the available keybindings.
|
|
||||||
|
|
||||||
#### Helm
|
|
||||||
|
|
||||||
Helm is setup according to this guide: [A Package in a league of its own: Helm](http://tuhdo.github.io/helm-intro.html).
|
|
||||||
|
|
||||||
You can learn Helm usage and key bindings following the guide. <kbd>C-c h</kbd> is Prelude's default prefix key for Helm.
|
|
||||||
If you don't remember any key binding, append <kbd>C-h</kbd> after <kbd>C-c h</kbd> for a list of key bindings in Helm.
|
|
||||||
|
|
||||||
If you love Helm and want to use Helm globally with enhanced `helm-find-files`, `helm-buffer-lists`..., you will have to also add `(require 'prelude-helm-everywhere)`.
|
|
||||||
When `prelude-helm-everywhere` is activated, Helm enables these global key bindings:
|
|
||||||
|
|
||||||
Key binding | Description
|
|
||||||
-------------------|----------------------------------------------
|
|
||||||
<kbd>M-x</kbd> | Run [helm-M-x](http://tuhdo.github.io/helm-intro.html#sec-3), an interactive version of <kbd>M-x</kdb>.
|
|
||||||
<kbd>M-y</kbd> | Run [helm-show-kill-ring](http://tuhdo.github.io/helm-intro.html#sec-4), shows the content of `kill-ring`.
|
|
||||||
<kbd>C-x b </kbd> | Run [helm-mini](http://tuhdo.github.io/helm-intro.html#sec-5), an interactive version of `C-x b` with more features.
|
|
||||||
<kbd>C-x C-f</kbd> | Run [helm-find-files](http://tuhdo.github.io/helm-intro.html#sec-6), an interactive version of `find-file` with more features.
|
|
||||||
<kbd>C-h f </kbd> | Run [helm-apropos](http://tuhdo.github.io/helm-intro.html#sec-13), an interactive version of `apropos-command`.
|
|
||||||
<kbd>C-h r</kbd> | Run [helm-info-emacs](http://tuhdo.github.io/helm-intro.html#sec-14), an interactive version of `info-emacs-manual`.
|
|
||||||
<kbd>C-h C-l </kbd>| Run `helm-locate-library` that can search for locations of any file loaded into Emacs.
|
|
||||||
|
|
||||||
This key binding is activated in `shell-mode`:
|
|
||||||
|
|
||||||
Key Binding | Description
|
|
||||||
-------------------|----------------------------------------------
|
|
||||||
<kbd>C-c C-l</kbd> | Run `helm-comint-input-ring` that shows `shell` history using Helm interface.
|
|
||||||
|
|
||||||
This key bindings is activated in `eshell-mode`:
|
|
||||||
|
|
||||||
Key Binding | Description
|
|
||||||
-------------------|----------------------------------------------
|
|
||||||
<kbd>C-c C-l</kbd> | Run `helm-eshell-history` that shows `eshell` history using Helm interface.
|
|
||||||
|
|
||||||
If you prefer Ido in everywhere, you should not add `prelude-helm-everywhere`, so you can use Helm along with Ido and Prelude's default commands.
|
|
||||||
|
|
||||||
You can always reactivate Helm with `(prelude-global-helm-global-mode-on)`.
|
|
||||||
|
|
||||||
**NOTICE**: In `helm-M-x`, you have to pass prefix argument *AFTER* you run `helm-M-x`,
|
|
||||||
because your prefix argument will be displayed in the modeline when in `helm-M-x`
|
|
||||||
buffer. Passing prefix argument **BEFORE** =helm-M-x= **has no effect**.
|
|
||||||
|
|
||||||
|
|
||||||
#### Key-chords
|
|
||||||
|
|
||||||
**Key-chords are available only when the `prelude-key-chord` module has been enabled.**
|
|
||||||
|
|
||||||
Keybinding | Description
|
|
||||||
-------------------|----------------------------------------------
|
|
||||||
<kbd>jj</kbd> | Jump to the beginning of a word(`avy-goto-word-1`)
|
|
||||||
<kbd>jk</kbd> | Jump to a character(`avy-goto-char`)
|
|
||||||
<kbd>jl</kbd> | Jump to the beginning of a line(`avy-goto-line`)
|
|
||||||
<kbd>JJ</kbd> | Jump back to previous buffer(`crux-switch-to-previous-buffer`)
|
|
||||||
<kbd>uu</kbd> | View edits as a tree(`undo-tree-visualize`)
|
|
||||||
<kbd>xx</kbd> | Executed extended command(`execute-extended-command`)
|
|
||||||
<kbd>yy</kbd> | Browse the kill ring(`browse-kill-ring`)
|
|
||||||
|
|
||||||
##### Disabling key-chords
|
|
||||||
|
|
||||||
In some cases you may not want to have a key-chord that is defined by prelude,
|
|
||||||
in which case you can disable the binding in your `personal.el` file by setting
|
|
||||||
its command to `nil`. For example, to disable the `jj` key-chord add the
|
|
||||||
following line:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(key-chord-define-global "jj" nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
If you're an `evil-mode` user you'll probably do well to disable `key-chord-mode` altogether:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(key-chord-mode -1)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### vim emulation
|
|
||||||
|
|
||||||
If you want to use vim keybindings inside of Emacs enable the `prelude-evil` module which provides
|
|
||||||
support for `evil-mode`.
|
|
||||||
|
|
||||||
### Cheatsheet
|
|
||||||
|
|
||||||
Use `C-h k <key>` (`<key>` are the ones listed on the left) or `C-h f <function>` (`<function>` are the ones listed on the right) to see the detailed explanation.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
#### PDF generation
|
|
||||||
|
|
||||||
Install [LaTeX](https://www.latex-project.org/get/)
|
|
||||||
|
|
||||||
``` bash
|
|
||||||
cd modules/doc
|
|
||||||
pdflatex prelude-cheatsheet.tex
|
|
||||||
```
|
|
||||||
|
|
||||||
#### PNG generation
|
|
||||||
|
|
||||||
Install [Poppler](https://poppler.freedesktop.org/)
|
|
||||||
|
|
||||||
``` bash
|
|
||||||
cd modules/doc
|
|
||||||
pdftocairo -png -singlefile prelude-cheatsheet.pdf cheatsheet
|
|
||||||
```
|
|
||||||
|
|
||||||
## Automatic package installation
|
|
||||||
|
|
||||||
The default Prelude installation comes with a bare minimum of
|
|
||||||
functionality. It will however install add-ons for various programming
|
|
||||||
languages and frameworks on demand. For instance - if you try to open
|
|
||||||
a `.clj` file `clojure-mode`, `cider` and Prelude's enhanced Lisp
|
|
||||||
configuration will be installed automatically for you.
|
|
||||||
|
|
||||||
You can, of course, install anything you wish manually as well.
|
|
||||||
|
|
||||||
### Color Themes
|
|
||||||
|
|
||||||
Emacs 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](#personalizing)
|
|
||||||
the following line:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(disable-theme 'zenburn)
|
|
||||||
```
|
|
||||||
|
|
||||||
Or you can use another theme altogether by adding something in `personal/preload` like:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq prelude-theme 'tango)
|
|
||||||
```
|
|
||||||
|
|
||||||
**Note** To use a non-built-in theme, like [Solarized](https://github.com/bbatsov/solarized-emacs),
|
|
||||||
you'll have to install it from MELPA first by `M-x package-install RET solarized-theme`. Then add
|
|
||||||
|
|
||||||
``` lisp
|
|
||||||
(setq prelude-theme 'solarized-dark)
|
|
||||||
```
|
|
||||||
in `personal/preload`.
|
|
||||||
|
|
||||||
Finally, if you don't want any theme at all, you can add this to your
|
|
||||||
`personal/preload`:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq prelude-theme nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Personalizing
|
|
||||||
|
|
||||||
All files you create under the `personal/` directory are yours for
|
|
||||||
personalization. There is no single special personal config file --
|
|
||||||
any files you create in the `personal/` directory will be loaded in
|
|
||||||
lexicographical order. The overall loading precedence is:
|
|
||||||
|
|
||||||
1. `personal/preload/*`
|
|
||||||
2. `core/`
|
|
||||||
3. `personal/prelude-modules.el` (or deprecated `prelude-modules.el`)
|
|
||||||
4. `personal/*`
|
|
||||||
|
|
||||||
#### Personalization Example
|
|
||||||
|
|
||||||
Suppose you want to configure go-mode to autoformat on each save. You
|
|
||||||
can create a file in `personal/`, let's call this one
|
|
||||||
`config-go-mode.el` and add the following to it.
|
|
||||||
|
|
||||||
``` emacs-lisp
|
|
||||||
(add-hook 'go-mode-hook
|
|
||||||
(lambda ()
|
|
||||||
(add-hook 'before-save-hook 'gofmt-before-save)
|
|
||||||
(setq tab-width 2)))
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Tips
|
|
||||||
|
|
||||||
**Fork** (instead of cloning) 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.
|
|
||||||
|
|
||||||
If you'd like to add some auto installation of packages in your
|
|
||||||
personal config use the following code:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(prelude-require-packages '(some-package some-other-package))
|
|
||||||
```
|
|
||||||
|
|
||||||
If you require just a single package you can also use:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(prelude-require-package 'some-package)
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Preloading personal config
|
|
||||||
|
|
||||||
Sometimes you might want to load code before Prelude has started loading. Prelude will automatically preload all
|
|
||||||
Emacs Lisp files in your `personal/preload` directory. Note that at this point you can't using anything from
|
|
||||||
Prelude, except a few variables like `prelude-dir`, etc (since nothing is yet loaded).
|
|
||||||
|
|
||||||
#### Disabling whitespace-mode
|
|
||||||
|
|
||||||
Although `whitespace-mode` is awesome, some people might find it too
|
|
||||||
intrusive. You can disable it in your
|
|
||||||
personal config with the following bit of code:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq prelude-whitespace nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
If you like `whitespace-mode`, but prefer it to not automatically
|
|
||||||
cleanup your file on save, you can disable that behavior by setting
|
|
||||||
`prelude-clean-whitespace-on-save` to `nil` in your config file with:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq prelude-clean-whitespace-on-save nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
The `prelude-clean-whitespace-on-save` setting can also be set on a
|
|
||||||
per-file or directory basis by using a file variable or a
|
|
||||||
`.dir-locals.el` file.
|
|
||||||
|
|
||||||
|
|
||||||
#### Disable flyspell-mode
|
|
||||||
|
|
||||||
If you're not fond of spellchecking on the fly:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq prelude-flyspell nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Caveats & Pitfalls
|
|
||||||
|
|
||||||
### Updating bundled packages
|
|
||||||
|
|
||||||
Generally it's a good idea to do a package update before running
|
|
||||||
updating Prelude, since the latest Prelude code might depend on newer
|
|
||||||
versions of the bundled packages than you would currently have
|
|
||||||
installed.
|
|
||||||
|
|
||||||
If you're doing manual Prelude updates you should always do a package update first.
|
|
||||||
|
|
||||||
`M-x package-list-packages RET U x`
|
|
||||||
|
|
||||||
That's not necessary if you're using `M-x prelude-update`, since it
|
|
||||||
will automatically update the installed packages.
|
|
||||||
|
|
||||||
### 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 macOS with
|
|
||||||
`homebrew` like this:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
brew install aspell --with-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.
|
|
||||||
|
|
||||||
### Warnings on 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).
|
|
||||||
|
|
||||||
If you'd like to be take this a step further and disable the arrow key navigation
|
|
||||||
completely put this in your [personal config](#personalizing):
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq guru-warn-only nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
To disable `guru-mode` completely add the following snippet to your
|
|
||||||
[personal config](#personalizing):
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq prelude-guru nil)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Customized C-a behavior
|
|
||||||
|
|
||||||
Prelude overrides `C-a` to behave as described
|
|
||||||
[here](http://emacsredux.com/blog/2013/05/22/smarter-navigation-to-the-beginning-of-a-line/). If
|
|
||||||
you don't like that simply add this to your [personal config](#personalizing):
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(global-set-key [remap move-beginning-of-line]
|
|
||||||
'move-beginning-of-line)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Poor ido matching performance on large datasets
|
|
||||||
|
|
||||||
Prelude's `ido` module swaps the default `ido` flex matching with the
|
|
||||||
more powerful [ido-flx](https://github.com/lewang/flx).
|
|
||||||
|
|
||||||
The sorting algorithm `flx` uses is more complex, but yields better results.
|
|
||||||
|
|
||||||
On slower machines, it may be necessary to lower `flx-ido-threshold` to
|
|
||||||
ensure a smooth experience.
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(setq flx-ido-threshold 1000)
|
|
||||||
```
|
|
||||||
|
|
||||||
You can always disable the improved sorting algorithm all together like this:
|
|
||||||
|
|
||||||
```lisp
|
|
||||||
(flx-ido-mode -1)
|
|
||||||
```
|
|
||||||
|
|
||||||
### Windows compatibility
|
|
||||||
|
|
||||||
While everything in Prelude should work fine in Windows, I test it only
|
|
||||||
with GNU/Linux & macOS, so there might be Windows-specific problems from time to
|
|
||||||
time. This situation will probably improve over time.
|
|
||||||
|
|
||||||
## Known issues
|
## Known issues
|
||||||
|
|
||||||
Check out the project's
|
Check out the project's
|
||||||
|
|
|
||||||
|
Before Width: | Height: | Size: 476 KiB After Width: | Height: | Size: 476 KiB |
125
doc/configuration.md
Normal file
125
doc/configuration.md
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
# Configuration
|
||||||
|
|
||||||
|
## Color Themes
|
||||||
|
|
||||||
|
Emacs 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:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(disable-theme 'zenburn)
|
||||||
|
```
|
||||||
|
|
||||||
|
Or you can use another theme altogether by adding something in `personal/preload` like:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq prelude-theme 'tango)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note** To use a non-built-in theme, like [Solarized](https://github.com/bbatsov/zenburn-emacs),
|
||||||
|
you'll have to install it from MELPA first by `M-x package-install RET solarized-theme`. Then add
|
||||||
|
|
||||||
|
``` lisp
|
||||||
|
(setq prelude-theme 'solarized-dark)
|
||||||
|
```
|
||||||
|
in `personal/preload`.
|
||||||
|
|
||||||
|
Finally, if you don't want any theme at all, you can add this to your
|
||||||
|
`personal/preload`:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq prelude-theme nil)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Personalizing
|
||||||
|
|
||||||
|
All files you create under the `personal/` directory are yours for
|
||||||
|
personalization. There is no single special personal config file --
|
||||||
|
any files you create in the `personal/` directory will be loaded in
|
||||||
|
lexicographical order. The overall loading precedence is:
|
||||||
|
|
||||||
|
1. `personal/preload/*`
|
||||||
|
2. `core/`
|
||||||
|
3. `prelude-modules.el`
|
||||||
|
4. `personal/*`
|
||||||
|
|
||||||
|
#### Personalization Example
|
||||||
|
|
||||||
|
Suppose you want to configure `go-mode` to autoformat on each save. You
|
||||||
|
can create a file in `personal/`, let's call this one
|
||||||
|
`config-go-mode.el` and add the following to it.
|
||||||
|
|
||||||
|
``` emacs-lisp
|
||||||
|
(add-hook 'go-mode-hook
|
||||||
|
(lambda ()
|
||||||
|
(add-hook 'before-save-hook 'gofmt-before-save)
|
||||||
|
(setq tab-width 2)))
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Tips
|
||||||
|
|
||||||
|
**Fork** (instead of cloning) 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.
|
||||||
|
|
||||||
|
If you'd like to add some auto installation of packages in your
|
||||||
|
personal config use the following code:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(prelude-require-packages '(some-package some-other-package))
|
||||||
|
```
|
||||||
|
|
||||||
|
If you require just a single package you can also use:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(prelude-require-package 'some-package)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Preloading personal config
|
||||||
|
|
||||||
|
Sometimes you might want to load code before Prelude has started loading. Prelude will automatically preload all
|
||||||
|
Emacs Lisp files in your `personal/preload` directory. Note that at this point you can't using anything from
|
||||||
|
Prelude, except a few variables like `prelude-dir`, etc (since nothing is yet loaded).
|
||||||
|
|
||||||
|
### Disabling whitespace-mode
|
||||||
|
|
||||||
|
Although `whitespace-mode` is awesome, some people might find it too
|
||||||
|
intrusive. You can disable it in your
|
||||||
|
personal config with the following bit of code:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq prelude-whitespace nil)
|
||||||
|
```
|
||||||
|
|
||||||
|
If you like `whitespace-mode`, but prefer it to not automatically
|
||||||
|
cleanup your file on save, you can disable that behavior by setting
|
||||||
|
`prelude-clean-whitespace-on-save` to `nil` in your config file with:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq prelude-clean-whitespace-on-save nil)
|
||||||
|
```
|
||||||
|
|
||||||
|
The `prelude-clean-whitespace-on-save` setting can also be set on a
|
||||||
|
per-file or directory basis by using a file variable or a
|
||||||
|
`.dir-locals.el` file.
|
||||||
|
|
||||||
|
|
||||||
|
### Disable flyspell-mode
|
||||||
|
|
||||||
|
If you're not fond of spellchecking on the fly:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq prelude-flyspell nil)
|
||||||
|
```
|
||||||
58
doc/contributing.md
Normal file
58
doc/contributing.md
Normal file
|
|
@ -0,0 +1,58 @@
|
||||||
|
## Issues
|
||||||
|
|
||||||
|
Report issues and suggest features and improvements on the
|
||||||
|
[GitHub issue tracker](https://github.com/bbatsov/prelude/issues). Don't ask
|
||||||
|
questions on the issue tracker - use the [support channels](support.md) instead.
|
||||||
|
|
||||||
|
If you want to file a bug, please provide all the necessary info listed in
|
||||||
|
our issue reporting template (it's loaded automatically when you create a
|
||||||
|
new GitHub issue).
|
||||||
|
|
||||||
|
## Patches
|
||||||
|
|
||||||
|
Patches in any form are always welcome! GitHub pull requests are even better! :-)
|
||||||
|
|
||||||
|
Before submitting a patch or a pull request make sure that your patch
|
||||||
|
is in line with the [contribution
|
||||||
|
guidelines](https://github.com/bbatsov/prelude/blob/master/CONTRIBUTING.md).
|
||||||
|
|
||||||
|
## Documentation
|
||||||
|
|
||||||
|
Good documentation is just as important as good code.
|
||||||
|
|
||||||
|
Consider improving and extending the
|
||||||
|
this manual and the
|
||||||
|
[community wiki](https://github.com/bbatsov/prelude/wiki).
|
||||||
|
|
||||||
|
### Working on the Manual
|
||||||
|
|
||||||
|
The manual is generated from the markdown files in the
|
||||||
|
[doc](https://github.com/bbatsov/prelude/tree/master/doc) folder of Prelude's
|
||||||
|
GitHub repo and is published to [Read the Docs](readthedocs.org). The
|
||||||
|
[MkDocs](http://www.mkdocs.org/) tool is used to convert the markdown sources to
|
||||||
|
HTML.
|
||||||
|
|
||||||
|
To make changes to the manual you simply have to change the files under
|
||||||
|
`doc`. The manual will be regenerated automatically when changes to those files
|
||||||
|
are merged in `master` (or the latest stable branch).
|
||||||
|
|
||||||
|
You can install `MkDocs` locally and use the command `mkdocs serve` to see the
|
||||||
|
result of changes you make to the manual locally:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
$ cd path/to/prelude/repo
|
||||||
|
$ mkdocs serve
|
||||||
|
```
|
||||||
|
|
||||||
|
If you want to make changes to the manual's page structure you'll have to edit
|
||||||
|
[mkdocs.yml](https://github.com/bbatsov/prelude/blob/master/mkdocs.yml).
|
||||||
|
|
||||||
|
## Donations
|
||||||
|
|
||||||
|
You can support the development of Prelude via
|
||||||
|
[Salt](https://salt.bountysource.com/teams/prelude),
|
||||||
|
[Patreon](https://www.patreon.com/bbatsov) and
|
||||||
|
[Liberapay](https://liberapay.com/bbatsov/donate).
|
||||||
|
|
||||||
|
[](https://liberapay.com/bbatsov/donate)
|
||||||
|
[](https://www.patreon.com/bbatsov)
|
||||||
15
doc/css/extra.css
Normal file
15
doc/css/extra.css
Normal file
|
|
@ -0,0 +1,15 @@
|
||||||
|
/* By default kbd doesn't stand out very much. Let's fix this! */
|
||||||
|
kbd {
|
||||||
|
padding: 3px 5px;
|
||||||
|
border: solid 1px #ccc;
|
||||||
|
background-color: #fcfcfc;
|
||||||
|
border-radius: 3px;
|
||||||
|
box-shadow: inset 0 -1px 0 #bbb;
|
||||||
|
display: inline-block;
|
||||||
|
}
|
||||||
|
|
||||||
|
/* The default font-size for code blocks is 75% which makes code
|
||||||
|
hard to read. */
|
||||||
|
code {
|
||||||
|
font-size: 90%;
|
||||||
|
}
|
||||||
3
doc/faq.md
Normal file
3
doc/faq.md
Normal file
|
|
@ -0,0 +1,3 @@
|
||||||
|
# Frequently Asked Questions
|
||||||
|
|
||||||
|
Coming soon...
|
||||||
18
doc/index.md
Normal file
18
doc/index.md
Normal file
|
|
@ -0,0 +1,18 @@
|
||||||
|
# Emacs Prelude
|
||||||
|
|
||||||
|
Prelude is an Emacs distribution that aims to enhance the default
|
||||||
|
Emacs experience. Prelude alters a lot of the default settings,
|
||||||
|
bundles a plethora of additional packages and adds its own core
|
||||||
|
library to the mix. The final product offers an easy to use Emacs
|
||||||
|
configuration for Emacs newcomers and lots of additional power for
|
||||||
|
Emacs power users.
|
||||||
|
|
||||||
|
Prelude is compatible **ONLY with GNU Emacs 25.1+**. In general you're
|
||||||
|
advised to always run Prelude with the latest Emacs - currently
|
||||||
|
**26.1**.
|
||||||
|
|
||||||
|
You can support the development of Prelude via
|
||||||
|
[PayPal](https://www.paypal.me/bbatsov),
|
||||||
|
[Salt](https://bountysource.com/teams/prelude),
|
||||||
|
[Patreon](https://www.patreon.com/bbatsov) and
|
||||||
|
[Liberapay](https://liberapay.com/bbatsov/donate).
|
||||||
122
doc/installation.md
Normal file
122
doc/installation.md
Normal file
|
|
@ -0,0 +1,122 @@
|
||||||
|
# Installation
|
||||||
|
|
||||||
|
## Installing Emacs
|
||||||
|
|
||||||
|
Obviously to use the Emacs Prelude you have to install Emacs
|
||||||
|
first. Have a look at
|
||||||
|
the
|
||||||
|
[WikEmacs articles on installing Emacs](http://wikemacs.org/index.php/Installing_Emacs).
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Automated
|
||||||
|
|
||||||
|
You can install **Emacs Prelude** 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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -L https://github.com/bbatsov/prelude/raw/master/utils/installer.sh | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Via Wget
|
||||||
|
|
||||||
|
If you're using `wget` type:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
wget --no-check-certificate https://github.com/bbatsov/prelude/raw/master/utils/installer.sh -O - | sh
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual
|
||||||
|
|
||||||
|
Make sure you do not have any `~/.emacs` file present.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone git://github.com/bbatsov/prelude.git path/to/local/repo
|
||||||
|
ln -s path/to/local/repo ~/.emacs.d
|
||||||
|
cd ~/.emacs.d
|
||||||
|
```
|
||||||
|
|
||||||
|
If you are using Windows, you should check what Emacs thinks the `~` directory is by running Emacs and typing `C-x d ~/<RET>`, and then adjust the command appropriately.
|
||||||
|
|
||||||
|
## Updating Prelude
|
||||||
|
|
||||||
|
### Manual update
|
||||||
|
|
||||||
|
The update procedure is fairly straightforward and consists of 3 steps:
|
||||||
|
|
||||||
|
#### Update all bundled packages
|
||||||
|
|
||||||
|
Just run <kbd>M-x package-list-packages RET U x</kbd>.
|
||||||
|
|
||||||
|
#### Update Prelude's code
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd path/to/prelude/installation
|
||||||
|
git pull
|
||||||
|
```
|
||||||
|
|
||||||
|
The `path/to/prelude/installation` is usually `~/.emacs.d` (at least
|
||||||
|
on Unix systems).
|
||||||
|
|
||||||
|
#### Restart Prelude
|
||||||
|
|
||||||
|
It's generally a good idea to stop Emacs after you do the update. The
|
||||||
|
next time Prelude starts it will install any new dependencies (if
|
||||||
|
there are such).
|
||||||
|
|
||||||
|
### Automatic update
|
||||||
|
|
||||||
|
Simply run <kbd>M-x prelude-update</kbd> from Emacs itself and restart Emacs afterwards.
|
||||||
|
|
||||||
|
## Pinning packages
|
||||||
|
|
||||||
|
By default, Prelude will install packages from the melpa and gnu package
|
||||||
|
repositories. Occasionally package integration can break when upgrading packages.
|
||||||
|
This can be avoided by pinning packages to stable versions in other repositories.
|
||||||
|
To do so, copy `prelude-pinned-packages.el` from the sample directory to
|
||||||
|
Prelude's root directory and adjust the [variables](https://www.gnu.org/software/emacs/manual/html_node/emacs/Package-Installation.html)
|
||||||
|
inside accordingly.
|
||||||
|
|
||||||
|
## Enabling additional modules
|
||||||
|
|
||||||
|
By default most of the modules that ship with Prelude are not loaded. For more information on the functionality provided by these modules visit the [docs](modules/index.md).
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
;;; Uncomment the modules you'd like to use and restart Prelude afterwards
|
||||||
|
|
||||||
|
(require 'prelude-c)
|
||||||
|
;; (require 'prelude-clojure)
|
||||||
|
;; (require 'prelude-coffee)
|
||||||
|
;; (require 'prelude-common-lisp)
|
||||||
|
;; (require 'prelude-css)
|
||||||
|
(require 'prelude-emacs-lisp)
|
||||||
|
(require 'prelude-erc)
|
||||||
|
;; (require 'prelude-erlang)
|
||||||
|
;; (require 'prelude-elixir)
|
||||||
|
;; (require 'prelude-haskell)
|
||||||
|
(require 'prelude-js)
|
||||||
|
;; (require 'prelude-latex)
|
||||||
|
(require 'prelude-lisp)
|
||||||
|
(require 'prelude-org)
|
||||||
|
(require 'prelude-perl)
|
||||||
|
;; (require 'prelude-python)
|
||||||
|
;; (require 'prelude-ruby)
|
||||||
|
;; (require 'prelude-scala)
|
||||||
|
(require 'prelude-scheme)
|
||||||
|
;; (require 'prelude-scss)
|
||||||
|
;; (require 'prelude-web)
|
||||||
|
(require 'prelude-xml)
|
||||||
|
```
|
||||||
|
|
||||||
|
You'll need to adjust your `prelude-modules.el` file once the
|
||||||
|
installation is done. If you are doing a manual install then you first
|
||||||
|
need to copy the `prelude-modules.el` available in the sample
|
||||||
|
directory to the root of `path/to/prelude/installation` and then
|
||||||
|
adjust that one.
|
||||||
|
|
||||||
|
After you've uncommented a module you should either restart Emacs or evaluate the module
|
||||||
|
`require` expression with <kbd>C-x C-e</kbd>.
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Prelude ERC Quickstart
|
# Prelude ERC
|
||||||
|
|
||||||
## Customizing Server list
|
## Customizing Server list
|
||||||
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Emacs Prelude Modules
|
# Modules
|
||||||
|
|
||||||
Prelude provides extra functionality through modules. Some modules may
|
Prelude provides extra functionality through modules. Some modules may
|
||||||
require extra steps to enable all functionality. These steps and the
|
require extra steps to enable all functionality. These steps and the
|
||||||
|
|
@ -11,7 +11,7 @@ following links.
|
||||||
- Common-Lisp
|
- Common-Lisp
|
||||||
- CSS
|
- CSS
|
||||||
- Emacs-Lisp
|
- Emacs-Lisp
|
||||||
- [ERC](prelude-erc.md)
|
- [ERC](erc.md)
|
||||||
- Erlang
|
- Erlang
|
||||||
- Elixir
|
- Elixir
|
||||||
- Haskell
|
- Haskell
|
||||||
|
|
@ -21,7 +21,7 @@ following links.
|
||||||
- Markdown
|
- Markdown
|
||||||
- Org
|
- Org
|
||||||
- Perl
|
- Perl
|
||||||
- [Python](prelude-python.md)
|
- [Python](python.md)
|
||||||
- Ruby
|
- Ruby
|
||||||
- Scala
|
- Scala
|
||||||
- Scheme
|
- Scheme
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Prelude Python Quickstart
|
# Prelude Python
|
||||||
|
|
||||||
## Python Mode
|
## Python Mode
|
||||||
|
|
||||||
33
doc/support.md
Normal file
33
doc/support.md
Normal file
|
|
@ -0,0 +1,33 @@
|
||||||
|
# Support
|
||||||
|
|
||||||
|
Prelude currently has several official & unofficial support channels.
|
||||||
|
|
||||||
|
For questions, suggestions and support refer to one of them. Please, don't
|
||||||
|
use the support channels to report issues, as this makes them harder to track.
|
||||||
|
|
||||||
|
## Gitter
|
||||||
|
|
||||||
|
Most internal discussions about the development of Prelude happen on its
|
||||||
|
[gitter channel](https://gitter.im/bbatsov/prelude). You can often find
|
||||||
|
Prelude's maintainers there and get some interesting news from the project's
|
||||||
|
kitchen.
|
||||||
|
|
||||||
|
## Mailing List
|
||||||
|
|
||||||
|
The [official mailing list](https://groups.google.com/forum/#!forum/emacs-prelude) is
|
||||||
|
hosted at Google Groups. It's a low-traffic list, so don't be too hesitant to subscribe.
|
||||||
|
|
||||||
|
## Freenode
|
||||||
|
|
||||||
|
If you're into IRC you can visit the `#prelude` channel on Freenode.
|
||||||
|
It's not actively
|
||||||
|
monitored by the Prelude maintainers themselves, but still you can get support
|
||||||
|
from other Prelude users there.
|
||||||
|
|
||||||
|
## Stackoverflow
|
||||||
|
|
||||||
|
We're also encouraging users to ask Prelude-related questions on StackOverflow.
|
||||||
|
|
||||||
|
When doing so you should use the
|
||||||
|
[Prelude](http://stackoverflow.com/questions/tagged/prelude) tag (ideally combined
|
||||||
|
with the tag `emacs`).
|
||||||
103
doc/troubleshooting.md
Normal file
103
doc/troubleshooting.md
Normal file
|
|
@ -0,0 +1,103 @@
|
||||||
|
# Troubleshooting
|
||||||
|
|
||||||
|
## Updating bundled packages
|
||||||
|
|
||||||
|
Generally it's a good idea to do a package update before running
|
||||||
|
updating Prelude, since the latest Prelude code might depend on newer
|
||||||
|
versions of the bundled packages than you would currently have
|
||||||
|
installed.
|
||||||
|
|
||||||
|
If you're doing manual Prelude updates you should always do a package update first.
|
||||||
|
|
||||||
|
`M-x package-list-packages RET U x`
|
||||||
|
|
||||||
|
That's not necessary if you're using `M-x prelude-update`, since it
|
||||||
|
will automatically update the installed packages.
|
||||||
|
|
||||||
|
## 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 macOS with
|
||||||
|
`homebrew` like this:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
brew install aspell --with-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.
|
||||||
|
|
||||||
|
## Warnings on 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).
|
||||||
|
|
||||||
|
If you'd like to be take this a step further and disable the arrow key navigation
|
||||||
|
completely put this in your personal config:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq guru-warn-only nil)
|
||||||
|
```
|
||||||
|
|
||||||
|
To disable `guru-mode` completely add the following snippet to your
|
||||||
|
personal Emacs config:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq prelude-guru nil)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Customized C-a behavior
|
||||||
|
|
||||||
|
Prelude overrides `C-a` to behave as described
|
||||||
|
[here](http://emacsredux.com/blog/2013/05/22/smarter-navigation-to-the-beginning-of-a-line/). If
|
||||||
|
you don't like that simply add this to your personal config:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(global-set-key [remap move-beginning-of-line]
|
||||||
|
'move-beginning-of-line)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Poor ido matching performance on large datasets
|
||||||
|
|
||||||
|
Prelude's `ido` module swaps the default `ido` flex matching with the
|
||||||
|
more powerful [ido-flx](https://github.com/lewang/flx).
|
||||||
|
|
||||||
|
The sorting algorithm `flx` uses is more complex, but yields better results.
|
||||||
|
|
||||||
|
On slower machines, it may be necessary to lower `flx-ido-threshold` to
|
||||||
|
ensure a smooth experience.
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq flx-ido-threshold 1000)
|
||||||
|
```
|
||||||
|
|
||||||
|
You can always disable the improved sorting algorithm all together like this:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(flx-ido-mode -1)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Windows compatibility
|
||||||
|
|
||||||
|
While everything in Prelude should work fine in Windows, I test it only
|
||||||
|
with GNU/Linux & macOS, so there might be Windows-specific problems from time to
|
||||||
|
time. This situation will probably improve over time.
|
||||||
275
doc/usage.md
Normal file
275
doc/usage.md
Normal file
|
|
@ -0,0 +1,275 @@
|
||||||
|
# Usage
|
||||||
|
|
||||||
|
## Running
|
||||||
|
|
||||||
|
Nothing fancy here. Just start Emacs as usual. Personally I run Emacs
|
||||||
|
in daemon mode:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
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)`.
|
||||||
|
|
||||||
|
You can also open a file with the cursor positioned directly on a specific line:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
emacsclient somefile:1234
|
||||||
|
```
|
||||||
|
|
||||||
|
This will open file 'somefile' and set cursor on line 1234.
|
||||||
|
|
||||||
|
## 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). Understanding the code is not
|
||||||
|
necessary of course. 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.
|
||||||
|
|
||||||
|
### Keymap
|
||||||
|
|
||||||
|
#### Global
|
||||||
|
|
||||||
|
Keybinding | Description
|
||||||
|
-------------------|------------------------------------------------------------
|
||||||
|
<kbd>C-x \\</kbd> | `align-regexp`
|
||||||
|
<kbd>C-+</kbd> | Increase font size(`text-scale-increase`).
|
||||||
|
<kbd>C--</kbd> | Decrease font size(`text-scale-decrease`).
|
||||||
|
<kbd>C-x O</kbd> | Go back to previous window (the inverse of `other-window` (`C-x o`)).
|
||||||
|
<kbd>C-^</kbd> | Join two lines into one(`crux-top-join-line`).
|
||||||
|
<kbd>C-x p</kbd> | Start `proced` (manage processes from Emacs; works only in Linux).
|
||||||
|
<kbd>C-x m</kbd> | Start `eshell`.
|
||||||
|
<kbd>C-x M-m</kbd> | Start your default shell.
|
||||||
|
<kbd>C-x C-m</kbd> | Alias for `M-x`.
|
||||||
|
<kbd>M-X</kbd> | Like `M-x` but limited to commands that are relevant to the active major mode.
|
||||||
|
<kbd>C-h A</kbd> | Run `apropos` (search in all Emacs symbols).
|
||||||
|
<kbd>C-h C-m</kbd> | Display key bindings of current major mode and descriptions of every binding.
|
||||||
|
<kbd>M-/</kbd> | Run `hippie-expand` (a replacement for the default `dabbrev-expand`).
|
||||||
|
<kbd>C-x C-b</kbd> | Open `ibuffer` (a replacement for the default `buffer-list`).
|
||||||
|
<kbd>F11</kbd> | Make the window full screen.
|
||||||
|
<kbd>F12</kbd> | Toggle the Emacs menu bar.
|
||||||
|
<kbd>C-x g</kbd> | Open Magit's status buffer.
|
||||||
|
<kbd>C-x M-g</kbd> | Open Magit's popup of popups.
|
||||||
|
<kbd>M-Z</kbd> | Zap up to char.
|
||||||
|
<kbd>C-=</kbd> | Run `expand-region` (incremental text selection).
|
||||||
|
<kbd>C-a</kbd> | Run `crux-move-beginning-of-line`. Read [this](http://emacsredux.com/blog/2013/05/22/smarter-navigation-to-the-beginning-of-a-line/) for details.
|
||||||
|
|
||||||
|
#### Prelude Mode
|
||||||
|
|
||||||
|
Keybinding | Description
|
||||||
|
-------------------|------------------------------------------------------------
|
||||||
|
<kbd>C-c o</kbd> | Open the currently visited file with an external program.
|
||||||
|
<kbd>C-c i</kbd> | Search for a symbol, only for buffers that contain code
|
||||||
|
<kbd>C-c g</kbd> | Search in Google for the thing under point (or an interactive query).
|
||||||
|
<kbd>C-c G</kbd> | Search in GitHub for the thing under point (or an interactive query).
|
||||||
|
<kbd>C-c y</kbd> | Search in YouTube for the thing under point (or an interactive query).
|
||||||
|
<kbd>C-c U</kbd> | Search in Duckduckgo for the thing under point (or an interactive query).
|
||||||
|
<kbd>C-S-RET</kbd> or <kbd>Super-o</kbd> | Insert an empty line above the current line and indent it properly.
|
||||||
|
<kbd>S-RET</kbd> or <kbd>M-o</kbd> | Insert an empty line and indent it properly (as in most IDEs).
|
||||||
|
<kbd>C-S-up</kbd> or <kbd>M-S-up</kbd> | Move the current line or region up.
|
||||||
|
<kbd>C-S-down</kbd> or <kbd>M-S-down</kbd>| Move the current line or region down.
|
||||||
|
<kbd>C-c n</kbd> | Fix indentation in buffer and strip whitespace.
|
||||||
|
<kbd>C-c f</kbd> | Open recently visited file.
|
||||||
|
<kbd>C-M-\\</kbd> | Indent region (if selected) or the entire buffer.
|
||||||
|
<kbd>C-c u</kbd> | Open a new buffer containing the contents of URL.
|
||||||
|
<kbd>C-c e</kbd> | Eval a bit of Emacs Lisp code and replace it with its result.
|
||||||
|
<kbd>C-c s</kbd> | Swap two active windows.
|
||||||
|
<kbd>C-c D</kbd> | Delete current file and buffer.
|
||||||
|
<kbd>C-c d</kbd> | Duplicate the current line (or region).
|
||||||
|
<kbd>C-c M-d</kbd> | Duplicate and comment the current line (or region).
|
||||||
|
<kbd>C-c r</kbd> | Rename the current buffer and its visiting file if any.
|
||||||
|
<kbd>C-c t</kbd> | Open a terminal emulator (`ansi-term`).
|
||||||
|
<kbd>C-c k</kbd> | Kill all open buffers except the one you're currently in.
|
||||||
|
<kbd>C-c TAB</kbd> | Indent and copy region to clipboard
|
||||||
|
<kbd>C-c I</kbd> | Open user's init file.
|
||||||
|
<kbd>C-c S</kbd> | Open shell's init file.
|
||||||
|
<kbd>C-c . +</kbd> | Increment integer at point. Default is +1.
|
||||||
|
<kbd>C-c . -</kbd> | Decrement integer at point. Default is -1.
|
||||||
|
<kbd>C-c . *</kbd> | Multiply integer at point. Default is *2.
|
||||||
|
<kbd>C-c . /</kbd> | Divide integer at point. Default is /2.
|
||||||
|
<kbd>C-c . \\</kbd> | Modulo integer at point. Default is modulo 2.
|
||||||
|
<kbd>C-c . ^</kbd> | Power to the integer at point. Default is ^2.
|
||||||
|
<kbd>C-c . <</kbd> | Left-shift integer at point. Default is 1 position to the left.
|
||||||
|
<kbd>C-c . ></kbd> | Right-shift integer at point. Default is 1 position to the right.
|
||||||
|
<kbd>C-c . #</kbd> | Convert integer at point to specified base. Default is 10.
|
||||||
|
<kbd>C-c . %</kbd> | Replace integer at point with another specified integer.
|
||||||
|
<kbd>C-c . '</kbd> | Perform arithmetic operations on integer at point. User specifies the operator.
|
||||||
|
<kbd>Super-r</kbd> | Recent files
|
||||||
|
<kbd>Super-j</kbd> | Join lines
|
||||||
|
<kbd>Super-k</kbd> | Kill whole line
|
||||||
|
<kbd>Super-m m</kbd> | Magit status
|
||||||
|
<kbd>Super-m l</kbd> | Magit log
|
||||||
|
<kbd>Super-m f</kbd> | Magit file log
|
||||||
|
<kbd>Super-m b</kbd> | Magit blame mode
|
||||||
|
|
||||||
|
**Note**: For various arithmetic operations, the prefix `C-c .` only needs to be pressed once for the first operation.
|
||||||
|
For subsequent operations, only the appropriate operations (i.e. `+`, `-`, `*`, `/`... needs to be pressed).
|
||||||
|
|
||||||
|
#### macOS modifier keys
|
||||||
|
|
||||||
|
Prelude does not mess by default with the standard mapping of `Command` (to `Super`) and `Option` (to `Meta`).
|
||||||
|
|
||||||
|
If you want to swap them add this to your personal config:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(setq mac-command-modifier 'meta)
|
||||||
|
(setq mac-option-modifier 'super)
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also temporarily swap them with `C-c w` (`M-x prelude-swap-meta-and-super`).
|
||||||
|
|
||||||
|
**Note**: I'd highly recommend to all macOS users to consider
|
||||||
|
[remapping Return to
|
||||||
|
Control](http://emacsredux.com/blog/2013/11/12/a-crazy-productivity-boost-remap-return-to-control/)
|
||||||
|
instead. That's an epic productivity boost and it's not as crazy as it sounds!
|
||||||
|
|
||||||
|
#### Projectile
|
||||||
|
|
||||||
|
[Projectile](https://github.com/bbatsov/projectile) is one of the essential packages bundled with Prelude.
|
||||||
|
It provides an easy way to navigate and switch projects. Take a look at its extensive documentation
|
||||||
|
to get a feel for everything you can do with Projectile.
|
||||||
|
|
||||||
|
Prelude adds an extra keymap prefix `s-p` (`s` stands for
|
||||||
|
`Super`) in addition to the standard one `C-c p`. By default on Windows keyboard
|
||||||
|
`Super` is mapped to the `Windows` key and on macOS keyboards `Super` is mapped
|
||||||
|
to the `Command` key.
|
||||||
|
|
||||||
|
If you ever forget any of Projectile's keybindings just do a:
|
||||||
|
|
||||||
|
<kbd>C-c p C-h</kbd> or <kbd>s-p C-h</kbd>
|
||||||
|
|
||||||
|
Alternatively you can just press <kbd>s-p</kbd> and wait for a moment
|
||||||
|
for `which-key` to kick in and show you the available keybindings.
|
||||||
|
|
||||||
|
#### Helm
|
||||||
|
|
||||||
|
Helm is setup according to this guide: [A Package in a league of its own: Helm](http://tuhdo.github.io/helm-intro.html).
|
||||||
|
|
||||||
|
You can learn Helm usage and key bindings following the guide. <kbd>C-c h</kbd> is Prelude's default prefix key for Helm.
|
||||||
|
If you don't remember any key binding, append <kbd>C-h</kbd> after <kbd>C-c h</kbd> for a list of key bindings in Helm.
|
||||||
|
|
||||||
|
If you love Helm and want to use Helm globally with enhanced `helm-find-files`, `helm-buffer-lists`..., you will have to also add `(require 'prelude-helm-everywhere)`.
|
||||||
|
When `prelude-helm-everywhere` is activated, Helm enables these global key bindings:
|
||||||
|
|
||||||
|
Key binding | Description
|
||||||
|
-------------------|----------------------------------------------
|
||||||
|
<kbd>M-x</kbd> | Run [helm-M-x](http://tuhdo.github.io/helm-intro.html#sec-3), an interactive version of <kbd>M-x</kdb>.
|
||||||
|
<kbd>M-y</kbd> | Run [helm-show-kill-ring](http://tuhdo.github.io/helm-intro.html#sec-4), shows the content of `kill-ring`.
|
||||||
|
<kbd>C-x b </kbd> | Run [helm-mini](http://tuhdo.github.io/helm-intro.html#sec-5), an interactive version of `C-x b` with more features.
|
||||||
|
<kbd>C-x C-f</kbd> | Run [helm-find-files](http://tuhdo.github.io/helm-intro.html#sec-6), an interactive version of `find-file` with more features.
|
||||||
|
<kbd>C-h f </kbd> | Run [helm-apropos](http://tuhdo.github.io/helm-intro.html#sec-13), an interactive version of `apropos-command`.
|
||||||
|
<kbd>C-h r</kbd> | Run [helm-info-emacs](http://tuhdo.github.io/helm-intro.html#sec-14), an interactive version of `info-emacs-manual`.
|
||||||
|
<kbd>C-h C-l </kbd>| Run `helm-locate-library` that can search for locations of any file loaded into Emacs.
|
||||||
|
|
||||||
|
This key binding is activated in `shell-mode`:
|
||||||
|
|
||||||
|
Key Binding | Description
|
||||||
|
-------------------|----------------------------------------------
|
||||||
|
<kbd>C-c C-l</kbd> | Run `helm-comint-input-ring` that shows `shell` history using Helm interface.
|
||||||
|
|
||||||
|
This key bindings is activated in `eshell-mode`:
|
||||||
|
|
||||||
|
Key Binding | Description
|
||||||
|
-------------------|----------------------------------------------
|
||||||
|
<kbd>C-c C-l</kbd> | Run `helm-eshell-history` that shows `eshell` history using Helm interface.
|
||||||
|
|
||||||
|
If you prefer Ido in everywhere, you should not add `prelude-helm-everywhere`, so you can use Helm along with Ido and Prelude's default commands.
|
||||||
|
|
||||||
|
You can always reactivate Helm with `(prelude-global-helm-global-mode-on)`.
|
||||||
|
|
||||||
|
**NOTICE**: In `helm-M-x`, you have to pass prefix argument *AFTER* you run `helm-M-x`,
|
||||||
|
because your prefix argument will be displayed in the modeline when in `helm-M-x`
|
||||||
|
buffer. Passing prefix argument **BEFORE** =helm-M-x= **has no effect**.
|
||||||
|
|
||||||
|
|
||||||
|
#### Key-chords
|
||||||
|
|
||||||
|
**Key-chords are available only when the `prelude-key-chord` module has been enabled.**
|
||||||
|
|
||||||
|
Keybinding | Description
|
||||||
|
-------------------|----------------------------------------------
|
||||||
|
<kbd>jj</kbd> | Jump to the beginning of a word(`avy-goto-word-1`)
|
||||||
|
<kbd>jk</kbd> | Jump to a character(`avy-goto-char`)
|
||||||
|
<kbd>jl</kbd> | Jump to the beginning of a line(`avy-goto-line`)
|
||||||
|
<kbd>JJ</kbd> | Jump back to previous buffer(`crux-switch-to-previous-buffer`)
|
||||||
|
<kbd>uu</kbd> | View edits as a tree(`undo-tree-visualize`)
|
||||||
|
<kbd>xx</kbd> | Executed extended command(`execute-extended-command`)
|
||||||
|
<kbd>yy</kbd> | Browse the kill ring(`browse-kill-ring`)
|
||||||
|
|
||||||
|
##### Disabling key-chords
|
||||||
|
|
||||||
|
In some cases you may not want to have a key-chord that is defined by prelude,
|
||||||
|
in which case you can disable the binding in your `personal.el` file by setting
|
||||||
|
its command to `nil`. For example, to disable the `jj` key-chord add the
|
||||||
|
following line:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(key-chord-define-global "jj" nil)
|
||||||
|
```
|
||||||
|
|
||||||
|
If you're an `evil-mode` user you'll probably do well to disable `key-chord-mode` altogether:
|
||||||
|
|
||||||
|
```lisp
|
||||||
|
(key-chord-mode -1)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### vim emulation
|
||||||
|
|
||||||
|
If you want to use vim keybindings inside of Emacs enable the `prelude-evil` module which provides
|
||||||
|
support for `evil-mode`.
|
||||||
|
|
||||||
|
### Cheatsheet
|
||||||
|
|
||||||
|
Use `C-h k <key>` (`<key>` are the ones listed on the left) or `C-h f <function>` (`<function>` are the ones listed on the right) to see the detailed explanation.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
#### PDF generation
|
||||||
|
|
||||||
|
Install [LaTeX](https://www.latex-project.org/get/)
|
||||||
|
|
||||||
|
``` bash
|
||||||
|
cd modules/doc
|
||||||
|
pdflatex prelude-cheatsheet.tex
|
||||||
|
```
|
||||||
|
|
||||||
|
#### PNG generation
|
||||||
|
|
||||||
|
Install [Poppler](https://poppler.freedesktop.org/)
|
||||||
|
|
||||||
|
``` bash
|
||||||
|
cd modules/doc
|
||||||
|
pdftocairo -png -singlefile prelude-cheatsheet.pdf cheatsheet
|
||||||
|
```
|
||||||
|
|
||||||
|
## Automatic package installation
|
||||||
|
|
||||||
|
The default Prelude installation comes with a bare minimum of
|
||||||
|
functionality. It will however install add-ons for various programming
|
||||||
|
languages and frameworks on demand. For instance - if you try to open
|
||||||
|
a `.clj` file `clojure-mode`, `cider` and Prelude's enhanced Lisp
|
||||||
|
configuration will be installed automatically for you.
|
||||||
|
|
||||||
|
You can, of course, install anything you wish manually as well.
|
||||||
22
mkdocs.yml
Normal file
22
mkdocs.yml
Normal file
|
|
@ -0,0 +1,22 @@
|
||||||
|
site_name: "Prelude: A sleek, modern, simple and powerful Emacs experience for everyone"
|
||||||
|
repo_url: https://github.com/bbatsov/prelude
|
||||||
|
copyright: "Copyright (C) 2019 Bozhidar Batsov and Prelude contributors"
|
||||||
|
docs_dir: doc
|
||||||
|
pages:
|
||||||
|
- Home: index.md
|
||||||
|
- Installation: installation.md
|
||||||
|
- Usage: usage.md
|
||||||
|
- Configuration: configuration.md
|
||||||
|
- Modules:
|
||||||
|
- Overview: modules/index.md
|
||||||
|
- ERC: modules/erc.md
|
||||||
|
- Python: modules/python.md
|
||||||
|
- FAQ: faq.md
|
||||||
|
- Troubleshooting: troubleshooting.md
|
||||||
|
- Contributing: contributing.md
|
||||||
|
- Support: support.md
|
||||||
|
extra_css:
|
||||||
|
- css/extra.css
|
||||||
|
markdown_extensions:
|
||||||
|
- admonition
|
||||||
|
theme: readthedocs
|
||||||
Loading…
Reference in a new issue