From 4490d51798892e6d0087a53398f3eb03f04111ad Mon Sep 17 00:00:00 2001 From: Bozhidar Batsov Date: Wed, 16 Jan 2019 14:31:52 +0200 Subject: [PATCH] Restructure the README into a manual --- README.md | 669 ------------------ {modules/doc => doc}/cheatsheet.png | Bin doc/configuration.md | 125 ++++ doc/contributing.md | 58 ++ doc/css/extra.css | 15 + doc/faq.md | 3 + doc/index.md | 18 + doc/installation.md | 122 ++++ .../doc/prelude-erc.md => doc/modules/erc.md | 22 +- modules/doc/README.md => doc/modules/index.md | 6 +- .../modules/python.md | 2 +- {modules/doc => doc}/prelude-cheatsheet.pdf | Bin {modules/doc => doc}/prelude-cheatsheet.tex | 0 doc/support.md | 33 + doc/troubleshooting.md | 103 +++ doc/usage.md | 275 +++++++ mkdocs.yml | 22 + 17 files changed, 789 insertions(+), 684 deletions(-) rename {modules/doc => doc}/cheatsheet.png (100%) create mode 100644 doc/configuration.md create mode 100644 doc/contributing.md create mode 100644 doc/css/extra.css create mode 100644 doc/faq.md create mode 100644 doc/index.md create mode 100644 doc/installation.md rename modules/doc/prelude-erc.md => doc/modules/erc.md (80%) rename modules/doc/README.md => doc/modules/index.md (83%) rename modules/doc/prelude-python.md => doc/modules/python.md (96%) rename {modules/doc => doc}/prelude-cheatsheet.pdf (100%) rename {modules/doc => doc}/prelude-cheatsheet.tex (100%) create mode 100644 doc/support.md create mode 100644 doc/troubleshooting.md create mode 100644 doc/usage.md create mode 100644 mkdocs.yml diff --git a/README.md b/README.md index e5fa8b2..92e5365 100644 --- a/README.md +++ b/README.md @@ -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 ~/`, 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 M-x package-list-packages RET U x. - -#### 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 M-x prelude-update 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 C-x C-e. - -## 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 --------------------|------------------------------------------------------------ -C-x \\ | `align-regexp` -C-+ | Increase font size(`text-scale-increase`). -C-- | Decrease font size(`text-scale-decrease`). -C-x O | Go back to previous window (the inverse of `other-window` (`C-x o`)). -C-^ | Join two lines into one(`crux-top-join-line`). -C-x p | Start `proced` (manage processes from Emacs; works only in Linux). -C-x m | Start `eshell`. -C-x M-m | Start your default shell. -C-x C-m | Alias for `M-x`. -M-X | Like `M-x` but limited to commands that are relevant to the active major mode. -C-h A | Run `apropos` (search in all Emacs symbols). -C-h C-m | Display key bindings of current major mode and descriptions of every binding. -M-/ | Run `hippie-expand` (a replacement for the default `dabbrev-expand`). -C-x C-b | Open `ibuffer` (a replacement for the default `buffer-list`). -F11 | Make the window full screen. -F12 | Toggle the Emacs menu bar. -C-x g | Open Magit's status buffer. -C-x M-g | Open Magit's popup of popups. -M-Z | Zap up to char. -C-= | Run `expand-region` (incremental text selection). -C-a | 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 --------------------|------------------------------------------------------------ -C-c o | Open the currently visited file with an external program. -C-c i | Search for a symbol, only for buffers that contain code -C-c g | Search in Google for the thing under point (or an interactive query). -C-c G | Search in GitHub for the thing under point (or an interactive query). -C-c y | Search in YouTube for the thing under point (or an interactive query). -C-c U | Search in Duckduckgo for the thing under point (or an interactive query). -C-S-RET or Super-o | Insert an empty line above the current line and indent it properly. -S-RET or M-o | Insert an empty line and indent it properly (as in most IDEs). -C-S-up or M-S-up | Move the current line or region up. -C-S-down or M-S-down| Move the current line or region down. -C-c n | Fix indentation in buffer and strip whitespace. -C-c f | Open recently visited file. -C-M-\\ | Indent region (if selected) or the entire buffer. -C-c u | Open a new buffer containing the contents of URL. -C-c e | Eval a bit of Emacs Lisp code and replace it with its result. -C-c s | Swap two active windows. -C-c D | Delete current file and buffer. -C-c d | Duplicate the current line (or region). -C-c M-d | Duplicate and comment the current line (or region). -C-c r | Rename the current buffer and its visiting file if any. -C-c t | Open a terminal emulator (`ansi-term`). -C-c k | Kill all open buffers except the one you're currently in. -C-c TAB | Indent and copy region to clipboard -C-c I | Open user's init file. -C-c S | Open shell's init file. -C-c . + | Increment integer at point. Default is +1. -C-c . - | Decrement integer at point. Default is -1. -C-c . * | Multiply integer at point. Default is *2. -C-c . / | Divide integer at point. Default is /2. -C-c . \\ | Modulo integer at point. Default is modulo 2. -C-c . ^ | Power to the integer at point. Default is ^2. -C-c . < | Left-shift integer at point. Default is 1 position to the left. -C-c . > | Right-shift integer at point. Default is 1 position to the right. -C-c . # | Convert integer at point to specified base. Default is 10. -C-c . % | Replace integer at point with another specified integer. -C-c . ' | Perform arithmetic operations on integer at point. User specifies the operator. -Super-r | Recent files -Super-j | Join lines -Super-k | Kill whole line -Super-m m | Magit status -Super-m l | Magit log -Super-m f | Magit file log -Super-m b | 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: - -C-c p C-h or s-p C-h - -Alternatively you can just press s-p 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. C-c h is Prelude's default prefix key for Helm. -If you don't remember any key binding, append C-h after C-c h 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 --------------------|---------------------------------------------- -M-x | Run [helm-M-x](http://tuhdo.github.io/helm-intro.html#sec-3), an interactive version of M-x. -M-y | Run [helm-show-kill-ring](http://tuhdo.github.io/helm-intro.html#sec-4), shows the content of `kill-ring`. -C-x b | Run [helm-mini](http://tuhdo.github.io/helm-intro.html#sec-5), an interactive version of `C-x b` with more features. -C-x C-f | Run [helm-find-files](http://tuhdo.github.io/helm-intro.html#sec-6), an interactive version of `find-file` with more features. -C-h f | Run [helm-apropos](http://tuhdo.github.io/helm-intro.html#sec-13), an interactive version of `apropos-command`. -C-h r | Run [helm-info-emacs](http://tuhdo.github.io/helm-intro.html#sec-14), an interactive version of `info-emacs-manual`. -C-h C-l | 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 --------------------|---------------------------------------------- -C-c C-l | Run `helm-comint-input-ring` that shows `shell` history using Helm interface. - -This key bindings is activated in `eshell-mode`: - -Key Binding | Description --------------------|---------------------------------------------- -C-c C-l | 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 --------------------|---------------------------------------------- -jj | Jump to the beginning of a word(`avy-goto-word-1`) -jk | Jump to a character(`avy-goto-char`) -jl | Jump to the beginning of a line(`avy-goto-line`) -JJ | Jump back to previous buffer(`crux-switch-to-previous-buffer`) -uu | View edits as a tree(`undo-tree-visualize`) -xx | Executed extended command(`execute-extended-command`) -yy | 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 ` (`` are the ones listed on the left) or `C-h f ` (`` 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 diff --git a/modules/doc/cheatsheet.png b/doc/cheatsheet.png similarity index 100% rename from modules/doc/cheatsheet.png rename to doc/cheatsheet.png diff --git a/doc/configuration.md b/doc/configuration.md new file mode 100644 index 0000000..c0f23a3 --- /dev/null +++ b/doc/configuration.md @@ -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) +``` diff --git a/doc/contributing.md b/doc/contributing.md new file mode 100644 index 0000000..1b22976 --- /dev/null +++ b/doc/contributing.md @@ -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) diff --git a/doc/css/extra.css b/doc/css/extra.css new file mode 100644 index 0000000..a124709 --- /dev/null +++ b/doc/css/extra.css @@ -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%; +} diff --git a/doc/faq.md b/doc/faq.md new file mode 100644 index 0000000..fe3a223 --- /dev/null +++ b/doc/faq.md @@ -0,0 +1,3 @@ +# Frequently Asked Questions + +Coming soon... diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..bead8a7 --- /dev/null +++ b/doc/index.md @@ -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). diff --git a/doc/installation.md b/doc/installation.md new file mode 100644 index 0000000..0e74d67 --- /dev/null +++ b/doc/installation.md @@ -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 ~/`, 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 M-x package-list-packages RET U x. + +#### 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 M-x prelude-update 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 C-x C-e. diff --git a/modules/doc/prelude-erc.md b/doc/modules/erc.md similarity index 80% rename from modules/doc/prelude-erc.md rename to doc/modules/erc.md index 5f61069..a9608ad 100644 --- a/modules/doc/prelude-erc.md +++ b/doc/modules/erc.md @@ -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) ``` diff --git a/modules/doc/README.md b/doc/modules/index.md similarity index 83% rename from modules/doc/README.md rename to doc/modules/index.md index 36422c8..c3a03d4 100644 --- a/modules/doc/README.md +++ b/doc/modules/index.md @@ -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 diff --git a/modules/doc/prelude-python.md b/doc/modules/python.md similarity index 96% rename from modules/doc/prelude-python.md rename to doc/modules/python.md index 8de3ff6..5657234 100644 --- a/modules/doc/prelude-python.md +++ b/doc/modules/python.md @@ -1,4 +1,4 @@ -# Prelude Python Quickstart +# Prelude Python ## Python Mode diff --git a/modules/doc/prelude-cheatsheet.pdf b/doc/prelude-cheatsheet.pdf similarity index 100% rename from modules/doc/prelude-cheatsheet.pdf rename to doc/prelude-cheatsheet.pdf diff --git a/modules/doc/prelude-cheatsheet.tex b/doc/prelude-cheatsheet.tex similarity index 100% rename from modules/doc/prelude-cheatsheet.tex rename to doc/prelude-cheatsheet.tex diff --git a/doc/support.md b/doc/support.md new file mode 100644 index 0000000..594857f --- /dev/null +++ b/doc/support.md @@ -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`). diff --git a/doc/troubleshooting.md b/doc/troubleshooting.md new file mode 100644 index 0000000..277c513 --- /dev/null +++ b/doc/troubleshooting.md @@ -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. diff --git a/doc/usage.md b/doc/usage.md new file mode 100644 index 0000000..dd01af0 --- /dev/null +++ b/doc/usage.md @@ -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 +-------------------|------------------------------------------------------------ +C-x \\ | `align-regexp` +C-+ | Increase font size(`text-scale-increase`). +C-- | Decrease font size(`text-scale-decrease`). +C-x O | Go back to previous window (the inverse of `other-window` (`C-x o`)). +C-^ | Join two lines into one(`crux-top-join-line`). +C-x p | Start `proced` (manage processes from Emacs; works only in Linux). +C-x m | Start `eshell`. +C-x M-m | Start your default shell. +C-x C-m | Alias for `M-x`. +M-X | Like `M-x` but limited to commands that are relevant to the active major mode. +C-h A | Run `apropos` (search in all Emacs symbols). +C-h C-m | Display key bindings of current major mode and descriptions of every binding. +M-/ | Run `hippie-expand` (a replacement for the default `dabbrev-expand`). +C-x C-b | Open `ibuffer` (a replacement for the default `buffer-list`). +F11 | Make the window full screen. +F12 | Toggle the Emacs menu bar. +C-x g | Open Magit's status buffer. +C-x M-g | Open Magit's popup of popups. +M-Z | Zap up to char. +C-= | Run `expand-region` (incremental text selection). +C-a | 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 +-------------------|------------------------------------------------------------ +C-c o | Open the currently visited file with an external program. +C-c i | Search for a symbol, only for buffers that contain code +C-c g | Search in Google for the thing under point (or an interactive query). +C-c G | Search in GitHub for the thing under point (or an interactive query). +C-c y | Search in YouTube for the thing under point (or an interactive query). +C-c U | Search in Duckduckgo for the thing under point (or an interactive query). +C-S-RET or Super-o | Insert an empty line above the current line and indent it properly. +S-RET or M-o | Insert an empty line and indent it properly (as in most IDEs). +C-S-up or M-S-up | Move the current line or region up. +C-S-down or M-S-down| Move the current line or region down. +C-c n | Fix indentation in buffer and strip whitespace. +C-c f | Open recently visited file. +C-M-\\ | Indent region (if selected) or the entire buffer. +C-c u | Open a new buffer containing the contents of URL. +C-c e | Eval a bit of Emacs Lisp code and replace it with its result. +C-c s | Swap two active windows. +C-c D | Delete current file and buffer. +C-c d | Duplicate the current line (or region). +C-c M-d | Duplicate and comment the current line (or region). +C-c r | Rename the current buffer and its visiting file if any. +C-c t | Open a terminal emulator (`ansi-term`). +C-c k | Kill all open buffers except the one you're currently in. +C-c TAB | Indent and copy region to clipboard +C-c I | Open user's init file. +C-c S | Open shell's init file. +C-c . + | Increment integer at point. Default is +1. +C-c . - | Decrement integer at point. Default is -1. +C-c . * | Multiply integer at point. Default is *2. +C-c . / | Divide integer at point. Default is /2. +C-c . \\ | Modulo integer at point. Default is modulo 2. +C-c . ^ | Power to the integer at point. Default is ^2. +C-c . < | Left-shift integer at point. Default is 1 position to the left. +C-c . > | Right-shift integer at point. Default is 1 position to the right. +C-c . # | Convert integer at point to specified base. Default is 10. +C-c . % | Replace integer at point with another specified integer. +C-c . ' | Perform arithmetic operations on integer at point. User specifies the operator. +Super-r | Recent files +Super-j | Join lines +Super-k | Kill whole line +Super-m m | Magit status +Super-m l | Magit log +Super-m f | Magit file log +Super-m b | 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: + +C-c p C-h or s-p C-h + +Alternatively you can just press s-p 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. C-c h is Prelude's default prefix key for Helm. +If you don't remember any key binding, append C-h after C-c h 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 +-------------------|---------------------------------------------- +M-x | Run [helm-M-x](http://tuhdo.github.io/helm-intro.html#sec-3), an interactive version of M-x. +M-y | Run [helm-show-kill-ring](http://tuhdo.github.io/helm-intro.html#sec-4), shows the content of `kill-ring`. +C-x b | Run [helm-mini](http://tuhdo.github.io/helm-intro.html#sec-5), an interactive version of `C-x b` with more features. +C-x C-f | Run [helm-find-files](http://tuhdo.github.io/helm-intro.html#sec-6), an interactive version of `find-file` with more features. +C-h f | Run [helm-apropos](http://tuhdo.github.io/helm-intro.html#sec-13), an interactive version of `apropos-command`. +C-h r | Run [helm-info-emacs](http://tuhdo.github.io/helm-intro.html#sec-14), an interactive version of `info-emacs-manual`. +C-h C-l | 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 +-------------------|---------------------------------------------- +C-c C-l | Run `helm-comint-input-ring` that shows `shell` history using Helm interface. + +This key bindings is activated in `eshell-mode`: + +Key Binding | Description +-------------------|---------------------------------------------- +C-c C-l | 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 +-------------------|---------------------------------------------- +jj | Jump to the beginning of a word(`avy-goto-word-1`) +jk | Jump to a character(`avy-goto-char`) +jl | Jump to the beginning of a line(`avy-goto-line`) +JJ | Jump back to previous buffer(`crux-switch-to-previous-buffer`) +uu | View edits as a tree(`undo-tree-visualize`) +xx | Executed extended command(`execute-extended-command`) +yy | 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 ` (`` are the ones listed on the left) or `C-h f ` (`` 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. diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..52e3af7 --- /dev/null +++ b/mkdocs.yml @@ -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