Restructure the README into a manual

This commit is contained in:
Bozhidar Batsov 2019-01-16 14:31:52 +02:00
parent 63c697c2f4
commit 4490d51798
17 changed files with 789 additions and 684 deletions

669
README.md
View file

@ -25,52 +25,6 @@ You can support the development of Prelude via
[![Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/bbatsov/donate)
[![Patreon](https://img.shields.io/badge/patreon-donate-orange.svg)](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
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
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.
![cheatsheet](/modules/doc/cheatsheet.png)
#### 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
Check out the project's

View file

Before

Width:  |  Height:  |  Size: 476 KiB

After

Width:  |  Height:  |  Size: 476 KiB

125
doc/configuration.md Normal file
View 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
View 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).
[![Liberapay](https://liberapay.com/assets/widgets/donate.svg)](https://liberapay.com/bbatsov/donate)
[![Patreon](https://img.shields.io/badge/patreon-donate-orange.svg)](https://www.patreon.com/bbatsov)

15
doc/css/extra.css Normal file
View 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
View file

@ -0,0 +1,3 @@
# Frequently Asked Questions
Coming soon...

18
doc/index.md Normal file
View 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
View 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>.

View file

@ -1,4 +1,4 @@
# Prelude ERC Quickstart
# Prelude ERC
## Customizing Server list
@ -6,11 +6,11 @@ If you want to join a list of servers on `M-x start-irc`, other than
the default list, please redefine the variable `my-fav-irc` as follows
in your personal config
``` emacs-lisp
(setq my-fav-irc '("irc.freenode.net"
``` emacs-lisp
(setq my-fav-irc '("irc.freenode.net"
"irc.oftc.net"
"irc.mozilla.org"
"irc.gnome.org"))
"irc.mozilla.org"
"irc.gnome.org"))
```
## Customizing Last Quit Message
@ -19,8 +19,8 @@ If you want to customize your IRC Last Quit Message from *Asta la
vista* to something more funkier, please redefine `bye-irc-message` as
follows
``` emacs-lisp
(setq bye-erc-message "adios")
``` emacs-lisp
(setq bye-erc-message "adios")
```
## Reading NickServ passwords from auth-source plugin
@ -28,8 +28,8 @@ follows
If you want to automatically authenticate while logging into IRC
servers set the `erc-prompt-for-password` to nil as follows
``` emacs-lisp
(setq erc-prompt-for-password nil)
``` emacs-lisp
(setq erc-prompt-for-password nil)
```
Now you can set password in plaintext in .authinfo file in the netRC
@ -45,6 +45,6 @@ to group all the ERC buffers into one perspective called `IRC` when
`start-irc` is called. To enable this set the `prelude-new-irc-persp`
variable to true as follows
``` emacs-lisp
(setq prelude-new-irc-persp t)
``` emacs-lisp
(setq prelude-new-irc-persp t)
```

View file

@ -1,4 +1,4 @@
# Emacs Prelude Modules
# Modules
Prelude provides extra functionality through modules. Some modules may
require extra steps to enable all functionality. These steps and the
@ -11,7 +11,7 @@ following links.
- Common-Lisp
- CSS
- Emacs-Lisp
- [ERC](prelude-erc.md)
- [ERC](erc.md)
- Erlang
- Elixir
- Haskell
@ -21,7 +21,7 @@ following links.
- Markdown
- Org
- Perl
- [Python](prelude-python.md)
- [Python](python.md)
- Ruby
- Scala
- Scheme

View file

@ -1,4 +1,4 @@
# Prelude Python Quickstart
# Prelude Python
## Python Mode

33
doc/support.md Normal file
View 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
View 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
View 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.
![cheatsheet](cheatsheet.png)
#### 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
View 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