emenel/doomemacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Rewrite project README

Browse source
This commit is contained in:
Henrik Lissner 2019-01-03 01:15:32 -05:00
parent 5e3d4c3ba2
commit 570bbb9957
No known key found for this signature in database
GPG key ID: 5F6C0EA160557395
1 changed files with 165 additions and 106 deletions
Download patch file Download diff file Expand all files Collapse all files

271
README.md
View file

@ -1,137 +1,196 @@
<img src="https://raw.githubusercontent.com/hlissner/doom-emacs/screenshots/main.png" alt="Main screenshot" />
<img src="https://img.shields.io/github/tag/hlissner/doom-emacs.svg?label=release"
alt="Current release"
align="left" />
<a href="https://travis-ci.org/hlissner/doom-emacs">
<img src="https://img.shields.io/travis/hlissner/doom-emacs/master.svg?label=master"
alt="build status (master)"
align="left" />
</a>
<a href="https://travis-ci.org/hlissner/doom-emacs">
<img src="https://img.shields.io/travis/hlissner/doom-emacs/master.svg?label=develop"
alt="build status (develop)"
align="left" />
</a>
<a href="https://discord.gg/bcZ6P3y">
<img src="https://img.shields.io/badge/Discord-blue.svg?logo=discord"
alt="Discord Server"
align="left" />
</a>
<p align="center">
<img src="https://img.shields.io/github/tag/hlissner/doom-emacs.svg?label=release&style=flat-square" alt="Current release" />
<a href="https://travis-ci.org/hlissner/doom-emacs"><img src="https://img.shields.io/travis/hlissner/doom-emacs/master.svg?label=master&style=flat-square" alt="build status (master)" /></a>
<a href="https://travis-ci.org/hlissner/doom-emacs"><img src="https://img.shields.io/travis/hlissner/doom-emacs/develop.svg?label=develop&style=flat-square" alt="build status (develop)" /></a>
<a href="https://discord.gg/bcZ6P3y"><img src="https://img.shields.io/badge/discord-chat-blue.svg?style=flat-square&logo=discord&colorB=%237289DA" alt="Chat on discord" /></a>
<img src="https://github.com/hlissner/doom-emacs/raw/screenshots/main.png" alt="Main screenshot" />
<a href="/../../wiki">wiki</a>&nbsp; |&nbsp;
<a href="/../../tree/screenshots">screenshots</a>&nbsp; |&nbsp;
<a href="/../../faq.org">faq</a>&nbsp; |&nbsp;
<a href="/../../wiki/FAQ#troubleshooting">troubleshooting</a>&nbsp; |&nbsp;
<a href="CHANGELOG.org">changelog</a>
</p>
- - -
<p align="center">
<a href="/../../wiki">Wiki</a> |
<a href="/../../tree/screenshots">Screenshots</a> |
<a href="/../../wiki/FAQ#troubleshooting">Troubleshooting</a> |
<a href="/../../wiki/FAQ">FAQ</a> |
<a href="/../develop/CHANGELOG.org">Changelog</a>
</p>
Quick start
-----------
- - -
```bash
git clone https://github.com/hlissner/doom-emacs ~/.emacs.d
~/.emacs.d/bin/doom quickstart
```
> Doom supports Emacs 25.3 and newer, but **Emacs 26.1 is recommended.** Doom
> works best on Linux & MacOS. Your mileage may vary on Windows.
Table of Contents
==================
- [What is Doom Emacs](#what-is-doom-emacs)
- [Doom's mantras](#dooms-mantras)
- [Feature highlights](#feature-highlights)
- [Getting Help](#getting-help)
- [Contributing](#contributing)
What is Doom Emacs
==================
<a href="http://ultravioletbat.deviantart.com/art/Yay-Evil-111710573">
<img src="/../screenshots/cacochan.png" align="right" />
<img src="https://github.com/hlissner/doom-emacs/raw/screenshots/cacochan.png" align="right" />
</a>
It is a story as old as time. A stubborn, shell-dwelling, and melodramatic
vimmer -- envious of the features of modern text editors -- spirals into despair
before finally succumbing to the [dark side][evil-mode]. This is his config.
before succumbing to the [dark side][evil-mode]. This is his config.
Doom strives to be fast, fabulous and hacker friendly. It is tailored for
neckbeards with blue belts or better in command-line-fu, Elisp and git.
Doom is a configuration for [GNU Emacs](https://www.gnu.org/software/emacs/). It
can be used as framework for your own configuration, or as a resource for fellow
Emacs enthusiasts who want to learn more about our favorite OS.
> Doom **only** supports Emacs >= 25.1, and is tested on Arch Linux 4.7+ and
> MacOS 10.11. YMMV on other platforms.
Doom's mantras
--------------
- **Gotta go fast.** Startup and runtime speed are high priorities; many
expensive, heavy-handed features and packages have been fine-tuned to that
end.
- **Hacker-friendly.** Doom caters to the command line denizen unafraid of
writing a little (or a lot of) code to tailor their editor. It also inherits
your shell configuration, warts 'n all, and expects frequent trips into the
terminal to manage Doom with its `bin/doom` utility.
- **Opinionated, but not stubborn.** Doom has _many_ opinions spread out across
its 120+ modules designed to iron out idiosynchrosies and provide a better and
more consistent baseline experience of Emacs and its plugins. However, they
mustn't ever compromise your ability to change, rewrite or disable any or all
of it, if you ask nicely.
- **Written to be read.** Doom's source ought to be self documenting and easy to
grok. Modules should be syntactically sweet and concise, and backend logic
should be explicit and abstraction-light. Where complexity arises, comments
and documentation shouldn't be far away.
- - -
Feature Highlights
------------------
- A declarative [package management system][doom:packages] with a command line
interface that combines package.el, [use-package] and [quelpa], allowing you
to install packages from anywhere.
- A [popup management system][doom:popups] with customizable rules to dictate
how temporary/disposable buffers are displayed.
- A vim-centric (and optional) experience with [evil-mode], including ports of
several popular vim plugins, <kbd>C-x</kbd> omnicompletion and a slew of
[custom ex commands][doom:commands].
- A Spacemacs-esque [keybinding scheme][doom:bindings], centered around leader
and localleader prefix keys (<kbd>SPC</kbd> and <kbd>SPC</kbd><kbd>m</kbd>, by
default).
- Indentation detection and optional integration with [url:editorconfig]. Let
someone else argue about tabs vs ___***spaces***___.
- Code completion for many languages, powered by
[company-mode][url:company-mode] (some may have external dependencies).
- Project-awareness powered by [projectile][url:projectile], with tools and an
API to navigate and manage projects, as well as project/framework-specific
minor modes and snippets libraries (and the ability to define your own).
- Project search (and replace) utilities, powered by
[the_silver_searcher][url:ag], [ripgrep][url:rg], git-grep and
[wgrep][url:wgrep], with integration for [ivy][url:ivy] (the default) and
[url:helm].
- Isolated and persistent workspaces powered by [persp-mode][url:persp-mode].
Also substitutes as vim tabs.
- Inline/live code evaluation (using [quickrun][url:quickrun]), with REPL
support for a variety of languages.
- A jump-to-definition/references implementation for all languages that tries to
"just work," resorting to mode-specific functionality, before falling back on
[dump-jump][url:dumb-jump].
## Quick start
```bash
git clone https://github.com/hlissner/doom-emacs ~/.emacs.d
cd ~/.emacs.d
make quickstart
```
Troubleshooting
===============
Don't forget to run `make` each time you modify init.el or update Doom!
Encountered strange behavior or an error? Here are some things to try before you
shoot off that bug report:
Visit the wiki for [a more detailed guide on installing, customizing and
grokking Doom][wiki].
- Run `bin/doom refresh`. This ensures Doom is properly set up and its autoloads
files are up-to-date.
- If you have byte-compiled your config (with `bin/doom compile`), see if
`bin/doom clean` makes your issue go away. Never debug issues with a
byte-compiled config, it will only make your job harder.
- Run `bin/doom doctor` to detect common issues in your development environment.
- Search Doom's issue tracker for mention of any error messages you've received.
- [Visit our FAQ][docs:faq] to see if your issue is listed.
## Feature highlights
If all else fails, [file that bug report][github:new-issue]! Please include the
behavior you've observed, the behavior you expected, and any error message in
the \*Messages\* buffer (can be opened with <kbd>SPC h m</kbd> or `M-x
view-echo-area-messages`). It'd be a great help if you included a backtrace with
them as well.
+ A fast, organized and opinionated Emacs configuration with a command line
interface.
+ A custom, declarative [package management system][doom-packages] that combines
package.el, [use-package] and [quelpa], allowing you to manage packages from
the command line and install packages from sources other than ELPA.
+ A [popup management system][doom-popups] (powered by [shackle]) that minimizes
the presence and footprint of temporary and/or disposable buffers.
+ 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].
+ Integration with [editorconfig]. Let someone else argue about tabs and spaces.
(spaces, duh).
+ Code completion for many languages, powered by [company-mode] (some languages
may have external dependencies).
+ Project-awareness powered by [projectile], with tools and an API to navigate
and manage projects and their files.
+ Fast project search (and replace) utilities, powered by [the_silver_searcher],
[ripgrep] and [wgrep], with integration for [ivy] (the default), [helm] and
ido.
+ Isolated and persistent workspaces powered by [persp-mode]. Also substitutes
for vim tabs.
+ Inline/live code evaluation (using [quickrun]), including REPLs for a variety
of languages.
We've also got [a Discord server][url:discord]. Hop on! We can help!
## Troubleshooting
Found a problem? Here are some things to try:
+ Run `make install` to ensure all plugins are installed.
+ `void-function` or `void-variable` errors could signal an out-of-date
autoloads file. Run `make autoloads` or `M-x doom//reload-autoloads` to update
it.
+ Scan for common OS/environment issues with `make doctor`.
+ **Never debug byte-compiled code. It will interfere in subtle ways.** Clean up
\*.elc files with `make clean` or `M-x doom//clean-byte-compiled-files`.
+ Check [the FAQ][wiki-troubleshooting] to see if your issue is mentioned.
+ Check the relevant module's README.org, if one exists. There may be extra
steps to getting certain features to work.
If all else has failed, [file a bug report][doom-new-issue].
## Contribute
Contributing
============
Doom (and my Emacs work in general) is a labor of love and incurable madness,
done on my spare time. It wasn't intended for public use, but I enjoy making
Doom a resource for others.
done on my spare time. If you'd like to support my work, I welcome
contributions:
If you'd like to support my efforts, I welcome contributions of any kind:
+ I love pull requests and bug reports. Elisp pointers are especially welcome.
Seriously, don't hesitate to [tell me my Elisp-fu sucks][doom-new-issue]!
+ Talk to me about Emacs workflow, ideas or tooling. Or talk to me about
gamedev, or pixel art, or anime, or programming, or the weather, or band camp.
Whatever. I don't mind. Holler at henrik@lissner.net.
- I love pull requests and bug reports. Check out the [Contributing
Guidelines][docs:contributing] (WIP) to find out how you can help out.
- I welcome Elisp pointers! Don't hesitate to [tell me my Elisp-fu
sucks][github:new-issue] (but please tell me why).
- Hop on [our Discord server][url:discord] and say hi! Help others out, hang out
or talk to me about Emacs, or gamedev, or programming, machine learning,
physics, pixel art, anime, gaming -- anything you like. Nourish this lonely
soul!
- If you'd like to support my work financially, consider buying me a drink
through [liberapay][url:liberapay] or [paypal][url:paypal]. Donations are a
great help. My work here contends with full-time studies, my ventures in indie
gamedev, and my freelance work.
[wiki]: /../../wiki
[wiki-conventions]: /../../wiki/Conventions
[wiki-modules]: /../../wiki/Modules
[wiki-customization]: /../../wiki/Customization
[wiki-troubleshooting]: /../../wiki/FAQ#troubleshooting
<!-- [docs:wiki]: docs/index.org -->
<!-- [docs:wiki-quickstart]: docs/getting-started.org -->
<!-- [docs:wiki-modules]: docs/modules.org -->
<!-- [docs:wiki-customization]: docs/customize.org -->
<!-- [docs:contributing]: docs/contribute.org -->
<!-- [docs:faq]: docs/faq.org -->
[docs:faq]: /../../wiki/FAQ
[doom-my-bindings]: modules/private/hlissner/+bindings.el
[doom-my-commands]: modules/private/hlissner/+commands.el
[doom-new-issue]: https://github.com/hlissner/doom-emacs/issues/new
[doom-packages]: core/autoload/packages.el
[doom-popups]: modules/ui/popup
[doom-theme]: https://github.com/hlissner/emacs-doom-theme
[github:new-issue]: https://github.com/hlissner/doom-emacs/issues/new
[doom:bindings]: modules/config/default/+bindings.el
[doom:commands]: modules/config/default/+evil-commands.el
[doom:packages]: core/autoload/packages.el
[doom:popups]: modules/feature/popup/README.org
[company-mode]: https://github.com/company-mode/company-mode
[editorconfig]: http://editorconfig.org/
[evil-mode]: https://github.com/emacs-evil/evil
[git-gutter-fringe]: https://github.com/syohex/emacs-git-gutter-fringe
[helm]: https://github.com/emacs-helm/helm
[ivy]: https://github.com/abo-abo/swiper
[persp-mode]: https://github.com/Bad-ptr/persp-mode.el
[projectile]: https://github.com/bbatsov/projectile
[quelpa]: https://github.com/quelpa/quelpa
[quickrun]: https://github.com/syohex/emacs-quickrun
[ripgrep]: https://github.com/BurntSushi/ripgrep
[shackle]: https://github.com/wasamasa/shackle
[the_silver_searcher]: https://github.com/ggreer/the_silver_searcher
[use-package]: https://github.com/jwiegley/use-package
[vim]: https://github.com/hlissner/.vim
[wgrep]: https://github.com/mhayashi1120/Emacs-wgrep
[url:discord]: https://discord.gg/bcZ6P3y
[url:liberapay]: https://liberapay.com/hlissner/donate
[url:paypal]: https://paypal.me/henriklissner/10
[url:company-mode]: https://github.com/company-mode/company-mode
[url:doom-themes]: https://github.com/hlissner/emacs-doom-themes
[url:editorconfig]: http://editorconfig.org/
[url:evil-mode]: https://github.com/emacs-evil/evil
[url:helm]: https://github.com/emacs-helm/helm
[url:ivy]: https://github.com/abo-abo/swiper
[url:persp-mode]: https://github.com/Bad-ptr/persp-mode.el
[url:projectile]: https://github.com/bbatsov/projectile
[url:quelpa]: https://github.com/quelpa/quelpa
[url:quickrun]: https://github.com/syohex/emacs-quickrun
[url:ripgrep]: https://github.com/BurntSushi/ripgrep
[url:the_silver_searcher]: https://github.com/ggreer/the_silver_searcher
[url:use-package]: https://github.com/jwiegley/use-package
[url:wgrep]: https://github.com/mhayashi1120/Emacs-wgrep