From 871201dad699adc72cb68afecf678d995e62daa6 Mon Sep 17 00:00:00 2001 From: Henrik Lissner Date: Sun, 26 Jan 2020 01:31:53 -0500 Subject: [PATCH] Minor doc/comment revision & fixes --- README.md | 67 ++++++++++++++++-------------- core/autoload/format.el | 2 +- core/templates/config.example.el | 4 +- docs/api.org | 1 + modules/editor/evil/+everywhere.el | 4 +- 5 files changed, 41 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index a1c603998cb..31228ae3127 100644 --- a/README.md +++ b/README.md @@ -31,11 +31,13 @@ **Quick start** ```bash -# Install emacs and ripgrep through your package manager, then... git clone https://github.com/hlissner/doom-emacs ~/.emacs.d ~/.emacs.d/bin/doom install ``` +More details, including dependencies and how to install Emacs, can be found [in +the documentation](docs/getting_started.org#install). + **Table of Contents** - [What is Doom Emacs](#what-is-doom-emacs) @@ -56,46 +58,47 @@ 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 succumbing to the [dark side][url:evil-mode]. This is his config. -Doom is a configuration for [GNU Emacs](https://www.gnu.org/software/emacs/) -designed to make Emacs faster and easier to customize. It can serve as framework -for your own configuration or a resource for fellow Emacs enthusiasts who want -to learn more about our favorite OS. +Doom is a configuration framework for [GNU +Emacs](https://www.gnu.org/software/emacs/) tailored for Emacs bankruptcy +veterans who want less framework in their frameworks and the performance of a +hand rolled config (or better). It can be a foundation for your own config or a +resource for Emacs enthusiasts to learn more about our favorite OS. ## Doom's mantras -- **Gotta go fast.** Startup and run-time performance are high priorities. - Expensive functionality (built-in or in plugins) is modified and optimized - toward this end, otherwise, they must be opt-in. -- **Close to metal.** There's less between you and vanilla Emacs, by design. - There's less to grok. Modules should be syntactically sweet and backend logic - explicit and abstraction-light. The code itself ought to be designed as if - grokking it were part of the user experience; and it is! -- **Opinionated, but not stubborn.** Doom is a bundle of reasonable defaults - and curated opinions, but you aren't stuck with it. Use as little or as much - of it as you like. Use it as-is as a complete Emacs distribution; disable - everything and use it as a baseline for your own; or anywhere in between. -- **Your system, your rules.** There are more ways to set up your programming - environment than there are dislikes on Youtube Rewind '18, so Doom and its - plugins promise not to *automatically* (and definitely not *silently*) install - system dependencies. This means fonts, packages and programs. `doom doctor` - will tell you what's missing though! +- **Gotta go fast.** Startup and run-time performance are priorities. Doom goes + beyond lazy loading packages by modifying them to be snappier and load lazier! +- **Close to metal.** There's less between you and vanilla Emacs by design. + There's less to grok, on top of Emacs. +- **Readability counts.** Internals ought to be written as if reading them were + part of the user experience, and it is! Modules should be syntactically sweet. + Backend logic should be functional (as much as elisp permits), abstraction + light and (hopefully) documented. +- **Opinionated, but not stubborn.** Doom is a bundle of reasonable defaults and + curated opinions, but all of it should be optional. Use as little or as much + of it as you like. +- **Your system, your rules.** There are more ways to set up your development + environment than there are dislikes on Youtube Rewind '18, so Doom leaves it + to you. Doom will not *automatically* install system dependencies (and will + coerce its plugins not to do so either). Use `doom doctor` to figure out + what's missing. ## Features +- Minimalistic good looks inspired by modern editors. +- A modular architecture for a more organized Emacs configuration. +- A custom elisp library to help simplify your config. +- (Optional) Vim-emulation powered by [evil-mode][url:evil-mode], including + ports of popular vim plugins and functionality. +- A declarative [package management system][doom:packages] (powered by + [straight.el][url:straight]) with a command line interface. Install packages + from anywhere, not just (M)ELPA. - A curated set of sane defaults for all packages, all (major) OSes, and Emacs itself. - Support for *many* programming languages. Too many to list. Includes syntax highlighting, linters/checker integration, inline code evaluation, code completion (where possible), REPLs, documentation lookups, snippets, and more! - Support for *many* tools, like docker, pass, ansible, terraform, and more. -- Minimalistic good looks inspired by modern editors. -- A modular architecture for a more organized Emacs configuration. -- A custom elisp library to help you simplify your config. -- A declarative [package management system][doom:packages] (powered by - [straight.el][url:straight]) with a command line interface. Install packages - from anywhere, not just (M)ELPA. -- Vim-emulation powered by [evil-mode][url:evil-mode], including ports of - popular vim plugins and functionality. - A Spacemacs-esque [keybinding scheme][doom:bindings], centered around leader and localleader prefix keys (SPC and SPCm, by default). @@ -107,9 +110,9 @@ to learn more about our favorite OS. snippets libraries. - Project search (and replace) utilities, powered by [ripgrep][url:ripgrep]. - Isolated and persistent workspaces (also substitutes for vim tabs). -- An environment variables file generator and loader, so that Emacs can - perfectly inherit your shell configuration. -- Everything is optional! +- An envvar file generator that captures a snapshot of your shell environment + for Doom to load at startup. No more struggling to get Emacs to inherit your + `PATH`, among other things. # Getting Help diff --git a/core/autoload/format.el b/core/autoload/format.el index 2be22513e24..c4429184d49 100644 --- a/core/autoload/format.el +++ b/core/autoload/format.el @@ -214,7 +214,7 @@ into faces or ANSI codes depending on the type of sesssion we're in." (defmacro print! (message &rest args) "Prints MESSAGE, formatted with ARGS, to stdout. -Always returns non-nil. +Returns non-nil if the message is a non-empty string. Can be colored using (color ...) blocks: diff --git a/core/templates/config.example.el b/core/templates/config.example.el index 0af845956aa..2f1430fdeda 100644 --- a/core/templates/config.example.el +++ b/core/templates/config.example.el @@ -4,8 +4,8 @@ ;; refresh' after modifying this file! -;; These are used for a number of things, particularly for GPG configuration, -;; some email clients, file templates and snippets. +;; Some functionality uses this to identify you, e.g. GPG configuration, email +;; clients, file templates and snippets. (setq user-full-name "John Doe" user-mail-address "john@doe.com") diff --git a/docs/api.org b/docs/api.org index a363d2add06..dc9f3d2a5b6 100644 --- a/docs/api.org +++ b/docs/api.org @@ -28,6 +28,7 @@ It is integrated into Helpful, in Doom. - [[#prependq][prependq!]] - [[#quiet][quiet!]] - [[#remove-hook][remove-hook!]] + - [[#setq][setq!]] - [[#setq-hook][setq-hook!]] - [[#unsetq-hook][unsetq-hook!]] - [[#use-package][use-package!]] diff --git a/modules/editor/evil/+everywhere.el b/modules/editor/evil/+everywhere.el index c519ea0f368..50f4d4c91d7 100644 --- a/modules/editor/evil/+everywhere.el +++ b/modules/editor/evil/+everywhere.el @@ -11,8 +11,8 @@ ;; their changes will override evil-collection's. ;; 3. Ideally, we'd do away with evil-collection entirely. It changes too often, ;; introduces breaking bugs too frequently, and I don't agree with all their -;; design choices. Regardless, it does mork than it causes trouble, so it may -;; be here to stay. +;; design choices. Regardless, it does more good than trouble, so it may be +;; here to stay. ;; 4. Adds `+evil-collection-disabled-list', to make it easier for users to ;; disable modules, and to reduce the effort required to maintain our copy of ;; `evil-collection-list' (now I can just copy it from time to time).