Rewrite README
This commit is contained in:
Henrik Lissner
parent
c962e1a47c
commit
68e973451d
1 changed files with 102 additions and 146 deletions
248
README.md
248
README.md
|
|
@ -3,178 +3,134 @@
|
||||||
[](https://travis-ci.org/hlissner/.emacs.d)
|
[](https://travis-ci.org/hlissner/.emacs.d)
|
||||||
[](./LICENSE)
|
[](./LICENSE)
|
||||||
|
|
||||||
[][sc]
|
[](/../screenshots)
|
||||||
|
|
||||||
|
- - -
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="/wiki">Documentation</a> |
|
||||||
|
<a href="/../screenshots">Screenshots</a> |
|
||||||
|
<a href="/wiki/Troubleshooting">Troubleshooting</a> |
|
||||||
|
<a href="/wiki/FAQ">FAQ</a> |
|
||||||
|
<a href="/CHANGELOG.org">Changelog</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
- - -
|
||||||
|
|
||||||
<a href="http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573">
|
<a href="http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573">
|
||||||
<img src="https://raw.githubusercontent.com/hlissner/.emacs.d/screenshots/cacochan.png" align="right" />
|
<img src="/../screenshots/cacochan.png" align="right" />
|
||||||
</a>
|
</a>
|
||||||
|
|
||||||
This is an Emacs configuration for a stubborn, shell-dwelling and melodramatic
|
It is a story as old as time. A stubborn, shell-dwelling, and melodramatic
|
||||||
vimmer disappointed with the text-editor status quo.
|
vimmer -- envious of the features of modern text editors -- spirals into despair
|
||||||
|
before he finally succumbs to the [dark side][evil-mode]. This is his config.
|
||||||
|
|
||||||
Doom tries to: look and act like modern editors (whatever that means to me on
|
DOOM's philosophy is simple: be **fast**, be **pretty**, and be **vim** (or
|
||||||
any given day), espouse vim's modal philosophy as best it can and strive to
|
better). It is tailored for neckbeards with a blue-belt or better in
|
||||||
surpass vim in any way possible. It fits my needs as a software developer, indie
|
command-line-fu who don't shy away from dabbling with Elisp.
|
||||||
game developer, scientist and doom enthusiast.
|
|
||||||
|
|
||||||
It was written for **Emacs 25.1+** on **MacOS 10.11+** and **Arch Linux 4.7+**.
|
Rip and tear. Until it is done.
|
||||||
I use [vim] everywhere else.
|
|
||||||
|
|
||||||
## Installation
|
> **Important:** Doom only supports Emacs >= 25.1, and is tailored for Arch
|
||||||
|
> Linux 4.7+ and Mac OS 10.11+.
|
||||||
|
|
||||||
|
- - -
|
||||||
|
|
||||||
|
## Quick start
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://github.com/hlissner/.emacs.d ~/.emacs.d
|
git clone https://github.com/hlissner/.emacs.d ~/.emacs.d
|
||||||
cd ~/.emacs.d
|
cd ~/.emacs.d
|
||||||
cp init.example.el init.el # maybe edit init.el
|
cp init.example.el init.el # maybe edit init.el
|
||||||
make install
|
make install
|
||||||
|
|
||||||
# Have problems? Run this to check for common issues with your setup
|
|
||||||
make doctor
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Once you've tweaked the config to your liking, you may optionally byte-compile
|
Visit the wiki for [a more detailed guide on installing, customizing and
|
||||||
it. DOOM is designed to benefit from this. It will boost startup times and make
|
grokking Doom][wiki].
|
||||||
Emacs feel a bit snappier in general.
|
|
||||||
|
|
||||||
```bash
|
## Feature highlights
|
||||||
make compile # may take a while
|
|
||||||
# or
|
|
||||||
make core # faster alternative; only compiles init.el & core files
|
|
||||||
|
|
||||||
# If you byte-compile, changes to the config won't take effect until you
|
+ A fast, organized and opinionated Emacs configuration with a command line
|
||||||
# recompile or delete the byte-compiled files with:
|
interface.
|
||||||
make clean
|
+ A custom, declarative [package management system][doom-packages] that combines
|
||||||
```
|
package.el, [use-package] and [quelpa]. This lets you install packages from
|
||||||
|
sources other than ELPA, as well as manage packages from the command line.
|
||||||
## Package Management
|
+ A [popup management system][doom-popups] (powered by [shackle]) that minimizes
|
||||||
|
the presence and footprint of temporary and/or disposable buffers.
|
||||||
Plugins can be managed from the command line with `make`:
|
+ A vim-like experience with [evil-mode], including ports for several vim
|
||||||
|
plugins, <kbd>C-x</kbd> omnicompletion and a slew of [custom ex commands][doom-my-commands].
|
||||||
```bash
|
+ Integration with [editorconfig]. Let someone else argue about tabs and spaces
|
||||||
make install # install missing plugins
|
(spaces, duh).
|
||||||
make update # update installed plugins
|
+ Code completion for a variety of languages, powered by [company-mode] (there
|
||||||
make autoremove # remove unused plugins
|
may be other dependencies for certain languages).
|
||||||
# be sure to run install and autoremove after modifying init.el
|
+ Project-awareness powered by [projectile], with tools to navigate and manage
|
||||||
|
projects and project files.
|
||||||
# run this if you change autoload files
|
+ Fast project search (and replace) utilities, powered by [the_silver_searcher],
|
||||||
make autoloads
|
[ripgrep] and [wgrep], with [ivy] (the default), [helm] and ido integration.
|
||||||
|
+ Isolated and persistent workspaces powered by [persp-mode]. This can
|
||||||
# this is the equivalent of running all four of the above commands
|
substitute for vim tabs.
|
||||||
make
|
+ Inline/live code evaluation (using [quickrun]), including REPLs for a variety
|
||||||
|
of languages.
|
||||||
# you can run any make command with DEBUG=1 for extra logging, and YES=1 to
|
|
||||||
# auto-accept confirmation prompts:
|
|
||||||
DEBUG=1 make install
|
|
||||||
YES=1 make update
|
|
||||||
```
|
|
||||||
|
|
||||||
These commands are also available from within Emacs:
|
|
||||||
|
|
||||||
+ `doom/packages-install`
|
|
||||||
+ `doom/packages-update`
|
|
||||||
+ `doom/packages-autoremove`
|
|
||||||
+ `doom/reload-autoloads`
|
|
||||||
|
|
||||||
## Deciphering my emacs.d
|
|
||||||
|
|
||||||
So you want to grok this madness. Here are a few suggestions:
|
|
||||||
|
|
||||||
* **[init.example.el](init.example.el)**: a birds eye view of available modules
|
|
||||||
* **[modules/README.org](modules/README.org)**: a primer into module structure
|
|
||||||
* **[modules/private/hlissner/+bindings.el](modules/private/hlissner/+bindings.el)**:
|
|
||||||
my custom keybinds.
|
|
||||||
* **[modules/private/hlissner/+commands.el](modules/private/hlissner/+commands.el)**:
|
|
||||||
my custom ex-commands (for [evil-mode]).
|
|
||||||
* **[modules/ui](modules/ui)**: the modules that makes my Emacs look the way it
|
|
||||||
does, including [my theme][doom-theme], modeline, dashboard and more.
|
|
||||||
* Find screenshots in the [screenshots branch][sc].
|
|
||||||
|
|
||||||
### Highlights
|
|
||||||
|
|
||||||
* A [popup management system](core/core-popups.el) using **[shackle]** to
|
|
||||||
minimize mental context switching while dealing with temporary or disposable
|
|
||||||
buffers.
|
|
||||||
* Per-project code-style settings with **[editorconfig]**. Let someone else
|
|
||||||
argue about tabs versus spaces (spaces, of course).
|
|
||||||
* Workspaces & session persistence with **[persp-mode]**. Provides tab emulation
|
|
||||||
that vaguely resembles vim's tabs.
|
|
||||||
* Project & workspace-restricted buffer navigation and functions.
|
|
||||||
* A vim-centric environment with **[evil-mode]**
|
|
||||||
* 2-character motions (ala vim-seek/vim-sneak) with **[evil-snipe]**
|
|
||||||
* Sublime Text-esque [multiple cursors][sc-multiedit] with
|
|
||||||
**[evil-mc]** and **[evil-multiedit]**
|
|
||||||
* <kbd>C-x</kbd> omnicompletion in insert mode
|
|
||||||
* A better `:global` with buffer highlighting
|
|
||||||
* A slew of [custom ex commands](modules/private/hlissner/+commands.el)
|
|
||||||
* Fast search utilities:
|
|
||||||
* Project and buffer navigation with **[ivy]**
|
|
||||||
* File browser sidebar with **[neotree]**
|
|
||||||
* Project text search powered by [the silver searcher][ag] and [ripgrep][rg]
|
|
||||||
(see `:ag` and `:rg`)
|
|
||||||
* Project search & replace with **[wgrep]**
|
|
||||||
* Interactive buffer search with **[swiper]**
|
|
||||||
* Inline/live code evaluation (using **[quickrun]**) and REPLs for a variety of
|
|
||||||
languages, including Ruby, Python, PHP, JS, Elisp, Haskell, Lua and more.
|
|
||||||
* [Minimalistic diffs in the fringe][sc-diffs] with **[git-gutter-fringe]**.
|
|
||||||
* A do-what-I-mean jump-to-definition implementation that tries its darnest to
|
|
||||||
find the definition of what you're looking at. It tries major-mode commands,
|
|
||||||
xref (experimental Emacs library), **[dumb-jump]**, ctags (WIP), then
|
|
||||||
**[ripgrep][rg]** or **[the_silver_searcher][ag]**.
|
|
||||||
* Snippets and file-templates with **[yasnippet]** & **[auto-yasnippet]**.
|
|
||||||
* A smarter, perdier, Atom-inspired mode-line that adds:
|
|
||||||
* evil-search/iedit/evil-substitute mode-line integration
|
|
||||||
* Macro-recording indicator
|
|
||||||
* Python/ruby version in mode-line (for rbenv/pyenv)
|
|
||||||
* Emacs as an:
|
|
||||||
* Email client (using mu4e & offlineimap)
|
|
||||||
* Presentation app (using org-tree-slides, ox-reveal, +present/big-mode
|
|
||||||
& impatient-mode)
|
|
||||||
* RSS feed reader (using elfeed)
|
|
||||||
* Word Processor (using LaTeX, Org and Markdown)
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
My config wasn't intended for public use, but I'm happy to help you use or crib
|
Found a problem? Here are some things to try:
|
||||||
from it.
|
|
||||||
|
|
||||||
+ If you have questions, drop me a line at henrik@lissner.net.
|
+ Make sure all plugins are installed with `make install`.
|
||||||
+ If you have issues running or setting up DOOM, use `make doctor` to diagnose
|
+ A `void-function` or `void-variable` might signal an out-of-date autoloads
|
||||||
any common problems.
|
file. Update it with `make autoloads`.
|
||||||
+ If you still can't make sense of it, run `DEBUG=1 make doctor` and include
|
+ Diagnose common OS/environment issues that could interfere with Emacs with
|
||||||
it [with your bug report][new-issue].
|
`make doctor`.
|
||||||
|
+ If you byte-compiled Doom, run `make clean` or `M-x doom/clean-compiled-files`
|
||||||
|
and restart Emacs. Never debug byte-compiled code, it will interfere with your
|
||||||
|
efforts in subtle (and not-so-subtle) ways.
|
||||||
|
|
||||||
**And please include steps to reproduce your issue, if possible.**
|
If all else fails, [file a bug report][doom-new-issue].
|
||||||
|
|
||||||
## Contributing
|
## Contribute
|
||||||
|
|
||||||
I welcome contributions of any kind: documentation, bug fixes/reports, extra
|
Doom (and my Emacs work in general) is a labor of love and incurable madness,
|
||||||
modules, even elisp tips. Really,
|
done on my free time. It wasn't intended for public use, but I enjoy making Doom
|
||||||
[don't hesitate to tell me my Elisp-fu sucks][new-issue]! I'm eager to learn.
|
a resource for others.
|
||||||
|
|
||||||
|
If you'd like to support my efforts, I welcome contributions of any kind:
|
||||||
|
|
||||||
|
+ I love pull requests and bug reports (read the [contribution
|
||||||
|
guidelines][wiki-contribute] first though!), and elisp pointers are especially
|
||||||
|
welcome. Seriously, don't hesitate to [tell me my Elisp-fu
|
||||||
|
sucks][doom-new-issue]!
|
||||||
|
+ I'm happy to discuss Emacs workflow, ideas or tooling. If you think I, Doom or
|
||||||
|
other Emacs users could benefit from them (or you just want to chat), drop me
|
||||||
|
a line at henrik@lissner.net. I'm eager to learn.
|
||||||
|
|
||||||
|
|
||||||
[ag]: https://github.com/ggreer/the_silver_searcher
|
[wiki]: /wiki
|
||||||
[auto-yasnippet]: https://melpa.org/#/auto-yasnippet
|
[wiki-contribute]: /wiki/Contribute
|
||||||
[company-mode]: https://melpa.org/#/company
|
[wiki-conventions]: /wiki/Conventions
|
||||||
|
[wiki-modules]: /wiki/Modules
|
||||||
|
[wiki-customization]: /wiki/Customization
|
||||||
|
|
||||||
|
[doom-my-bindings]: modules/private/hlissner/+bindings.el
|
||||||
|
[doom-my-commands]: modules/private/hlissner/+commands.el
|
||||||
|
[doom-new-issue]: https://github.com/hlissner/.emacs.d/issues/new
|
||||||
|
[doom-packages]: core/autoload/packages.el
|
||||||
|
[doom-popups]: core/core-popups.el
|
||||||
[doom-theme]: https://github.com/hlissner/emacs-doom-theme
|
[doom-theme]: https://github.com/hlissner/emacs-doom-theme
|
||||||
[dumb-jump]: https://melpa.org/#/dumb-jump
|
|
||||||
|
[company-mode]: https://github.com/company-mode/company-mode
|
||||||
[editorconfig]: http://editorconfig.org/
|
[editorconfig]: http://editorconfig.org/
|
||||||
[evil-mc]: https://github.com/gabesoft/evil-mc
|
[evil-mode]: https://github.com/emacs-evil/evil
|
||||||
[evil-mode]: https://melpa.org/#/evil
|
[git-gutter-fringe]: https://github.com/syohex/emacs-git-gutter-fringe
|
||||||
[evil-multiedit]: https://melpa.org/#/evil-multiedit
|
[helm]: https://github.com/emacs-helm/helm
|
||||||
[evil-snipe]: https://melpa.org/#/evil-snipe
|
[ivy]: https://github.com/abo-abo/swiper
|
||||||
[git-gutter-fringe]: https://melpa.org/#/git-gutter-fringe
|
[persp-mode]: https://github.com/Bad-ptr/persp-mode.el
|
||||||
[ivy]: https://melpa.org/#/ivy
|
[projectile]: https://github.com/bbatsov/projectile
|
||||||
[neotree]: https://melpa.org/#/neotree
|
[quelpa]: https://github.com/quelpa/quelpa
|
||||||
[new-issue]: https://github.com/hlissner/.emacs.d/issues/new
|
[quickrun]: https://github.com/syohex/emacs-quickrun
|
||||||
[persp-mode]: https://melpa.org/#/persp-mode
|
[ripgrep]: https://github.com/BurntSushi/ripgrep
|
||||||
[quickrun]: https://melpa.org/#/quickrun
|
[shackle]: https://github.com/wasamasa/shackle
|
||||||
[rg]: https://github.com/BurntSushi/ripgrep
|
[the_silver_searcher]: https://github.com/ggreer/the_silver_searcher
|
||||||
[sc-diffs]: https://github.com/hlissner/.emacs.d/blob/screenshots/git-gutter.png?raw=true
|
[use-package]: https://github.com/jwiegley/use-package
|
||||||
[sc-multiedit]: https://raw.githubusercontent.com/hlissner/evil-multiedit/screenshots/main.gif?raw=true
|
|
||||||
[sc]: https://github.com/hlissner/.emacs.d/tree/screenshots
|
|
||||||
[shackle]: https://melpa.org/#/shackle
|
|
||||||
[swiper]: https://melpa.org/#/swiper
|
|
||||||
[vim]: https://github.com/hlissner/.vim
|
[vim]: https://github.com/hlissner/.vim
|
||||||
[wgrep]: https://melpa.org/#/wgrep
|
[wgrep]: https://github.com/mhayashi1120/Emacs-wgrep
|
||||||
[yasnippet]: https://melpa.org/#/yasnippet
|
|
||||||
[yay-evil]: http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573
|
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue