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

merge: rewrite-docs

Browse source 
I've omitted docs/*.org from this merge, as there is still work left to
do there, but I am pushing the module docs early so folks can benefit
from the new docs sooner.
This commit is contained in:
Henrik Lissner 2022-08-03 03:23:34 +02:00
commit 1f8bf7accb
No known key found for this signature in database
GPG key ID: B60957CA074D39A3
179 changed files with 13125 additions and 8630 deletions
Download patch file Download diff file Expand all files Collapse all files

5
.dir-locals.el
View file

@ -1,3 +1,2 @@
((nil (git-commit-major-mode . git-commit-elisp-text-mode)
(fill-column . 80))
(org-mode (buffer-read-only . t)))
((nil (git-commit-major-mode . git-commit-elisp-text-mode)
(fill-column . 80)))

1677
docs/getting_started.org
View file

File diff suppressed because it is too large Load diff

226
docs/modules.org
View file

@ -1,226 +0,0 @@
#+TITLE: Module Index
#+STARTUP: nofold
Functionality in Doom is divided into collections of code called modules (à la
Spacemacs' layers). A module is a bundle of packages, configuration and
commands, organized into a unit that can be enabled or disabled by adding or
removing them from your ~doom!~ block in =$DOOMDIR/init.el=.
* Table of Contents :TOC:
- [[#app][:app]]
- [[#checkers][:checkers]]
- [[#completion][:completion]]
- [[#config][:config]]
- [[#editor][:editor]]
- [[#emacs][:emacs]]
- [[#email][:email]]
- [[#input][:input]]
- [[#lang][:lang]]
- [[#os][:os]]
- [[#term][:term]]
- [[#tools][:tools]]
- [[#ui][:ui]]
* :app
Application modules are complex and opinionated modules that transform Emacs
toward a specific purpose. They may have additional dependencies and *should be
loaded last*, before =:config= modules.
+ [[file:../modules/app/calendar/README.org][calendar]] - TODO
+ [[file:../modules/app/emms/README.org][emms]] - TODO
+ [[file:../modules/app/everywhere/README.org][everywhere]] - TODO
+ [[file:../modules/app/irc/README.org][irc]] - how neckbeards socialize
+ [[file:../modules/app/rss/README.org][rss]] =+org= - an RSS client in Emacs
+ [[file:../modules/app/twitter/README.org][twitter]] - A twitter client for Emacs
* :checkers
+ syntax =+childframe= - Live error/warning highlights
+ [[file:../modules/checkers/spell/README.org][spell]] =+aspell +flyspell +enchant +everywhere +hunspell= - Spell checking
+ [[file:../modules/checkers/grammar/README.org][grammar]] - TODO
* :completion
Modules that provide new interfaces or frameworks for completion, including code
completion.
+ [[file:../modules/completion/company/README.org][company]] =+childframe +tng= - The ultimate code completion backend
+ helm =+fuzzy +childframe= - *Another* search engine for love and life
+ ido - The /other/ *other* search engine for love and life
+ [[file:../modules/completion/ivy/README.org][ivy]] =+fuzzy +prescient +childframe +icons= - /The/ search engine for love and life
+ [[file:../modules/completion/vertico/README.org][vertico]] =+icons= - The search engine of the future
* :config
Modules that configure Emacs one way or another, or focus on making it easier
for you to customize it yourself. It is best to load these last.
+ [[file:../modules/config/literate/README.org][literate]] - For users with literate configs. This will tangle+compile a
config.org in your ~doom-private-dir~ when it changes.
+ [[file:../modules/config/default/README.org][default]] =+bindings +smartparens= - The default module sets reasonable defaults
for Emacs. It also provides a Spacemacs-inspired keybinding scheme and a
smartparens config. Use it as a reference for your own modules.
* :editor
Modules that affect and augment your ability to manipulate or insert text.
+ [[file:../modules/editor/evil/README.org][evil]] =+everywhere= - transforms Emacs into Vim
+ [[file:../modules/editor/file-templates/README.org][file-templates]] - Auto-inserted templates in blank new files
+ [[file:../modules/editor/fold/README.org][fold]] - universal code folding
+ format =+onsave= - TODO
+ god - TODO
+ [[file:../modules/editor/lispy/README.org][lispy]] - TODO
+ multiple-cursors - TODO
+ [[file:../modules/editor/objed/README.org][objed]] =+manual= - TODO
+ [[file:../modules/editor/parinfer/README.org][parinfer]] - TODO
+ rotate-text - TODO
+ [[file:../modules/editor/snippets/README.org][snippets]] - Snippet expansion for lazy typists
+ [[file:../modules/editor/word-wrap/README.org][word-wrap]] - soft wrapping with language-aware indent
* :emacs
Modules that reconfigure or augment packages or features built into Emacs.
+ [[file:../modules/emacs/dired/README.org][dired]] =+ranger +icons= - TODO
+ electric - TODO
+ [[file:../modules/emacs/ibuffer/README.org][ibuffer]] =+icons= - TODO
+ [[file:../modules/emacs/undo/README.org][undo]] =+tree= - A smarter, more intuitive & persistent undo history
+ [[file:../modules/emacs/vc/README.org][vc]] - TODO
* :email
+ [[file:../modules/email/mu4e/README.org][mu4e]] =+org +gmail= - TODO
+ [[file:../modules/email/notmuch/README.org][notmuch]] - TODO
+ wanderlust =+gmail= - TODO
* :input
+ [[file:../modules/input/bidi/README.org][bidi]] - (tfel ot) thgir etirw uoy gnipleh
+ [[file:../modules/input/chinese/README.org][chinese]] - TODO
+ [[file:../modules/input/japanese/README.org][japanese]] - TODO
+ [[file:../modules/input/layout/README.org][layout]] =+azerty +bepo= - TODO
* :lang
Modules that bring support for a language or group of languages to Emacs.
+ [[file:../modules/lang/agda/README.org][agda]] =+local= - TODO
+ [[file:../modules/lang/beancount/README.org][beancount]] =+lsp= - TODO
+ [[file:../modules/lang/cc/README.org][cc]] =+lsp= - TODO
+ [[file:../modules/lang/clojure/README.org][clojure]] =+lsp= - TODO
+ common-lisp - TODO
+ [[file:../modules/lang/coq/README.org][coq]] - TODO
+ [[file:../modules/lang/crystal/README.org][crystal]] - TODO
+ [[file:../modules/lang/csharp/README.org][csharp]] =+lsp +unity= - TODO
+ [[file:../modules/lang/dart/README.org][dart]] =+lsp +flutter=
+ data - TODO
+ [[file:../modules/lang/elixir/README.org][elixir]] =+lsp= - TODO
+ elm =+lsp= - TODO
+ [[file:../modules/lang/emacs-lisp/README.org][emacs-lisp]] - TODO
+ [[file:../modules/lang/erlang/README.org][erlang]] =+lsp= - TODO
+ [[file:../modules/lang/ess/README.org][ess]] =+lsp= - TODO
+ [[file:../modules/lang/factor/README.org][factor]] - TODO
+ [[file:../modules/lang/faust/README.org][faust]] - TODO
+ [[file:../modules/lang/fsharp/README.org][fsharp]] =+lsp= - TODO
+ [[file:../modules/lang/fstar/README.org][fstar]] - F* support
+ [[file:../modules/lang/gdscript/README.org][gdscript]] =+lsp= - TODO
+ [[file:../modules/lang/go/README.org][go]] =+lsp= - TODO
+ [[file:../modules/lang/haskell/README.org][haskell]] =+lsp= - TODO
+ hy - TODO
+ [[file:../modules/lang/idris/README.org][idris]] - TODO
+ java =+meghanada +eclim +lsp= - TODO
+ [[file:../modules/lang/javascript/README.org][javascript]] =+lsp= - JavaScript, TypeScript, and CoffeeScript support
+ [[file:../modules/lang/json/README.org][json]] =+lsp= - TODO
+ [[file:../modules/lang/julia/README.org][julia]] =+lsp= - TODO
+ [[file:../modules/lang/kotlin/README.org][kotlin]] =+lsp= - TODO
+ [[file:../modules/lang/latex/README.org][latex]] =+latexmk +cdlatex +fold +lsp= - TODO
+ lean - TODO
+ [[file:../modules/lang/ledger/README.org][ledger]] - TODO
+ [[file:../modules/lang/lua/README.org][lua]] =+fennel +moonscript= - TODO
+ [[file:../modules/lang/markdown/README.org][markdown]] =+grip= - TODO
+ [[file:../modules/lang/nim/README.org][nim]] - TODO
+ [[file:../modules/lang/nix/README.org][nix]] - TODO
+ [[file:../modules/lang/ocaml/README.org][ocaml]] =+lsp= - TODO
+ [[file:../modules/lang/org/README.org][org]] =+brain +dragndrop +gnuplot +hugo +ipython +journal +jupyter +noter +pandoc +pomodoro +present +pretty +roam= - TODO
+ [[file:../modules/lang/php/README.org][php]] =+hack +lsp= - TODO
+ plantuml - TODO
+ purescript =+lsp= - TODO
+ [[file:../modules/lang/python/README.org][python]] =+cython +lsp +pyright +pyenv +conda +poetry= - TODO
+ qt - TODO
+ [[file:../modules/lang/racket/README.org][racket]] =+lsp +xp= - TODO
+ [[file:../modules/lang/raku/README.org][raku]] - TODO
+ [[file:../modules/lang/rest/README.org][rest]] - TODO
+ rst - TODO
+ [[file:../modules/lang/ruby/README.org][ruby]] =+lsp +rvm +rbenv +rails +chruby=
+ [[file:../modules/lang/rust/README.org][rust]] =+lsp= - TODO
+ [[file:../modules/lang/scala/README.org][scala]] =+lsp= - TODO
+ [[file:../modules/lang/scheme/README.org][scheme]] =+chez +chibi +chicken +gambit +gauche +guile +kawa +mit +racket= - TODO
+ [[file:../modules/lang/sh/README.org][sh]] =+fish +lsp +powershell= - TODO
+ [[file:../modules/lang/sml/README.org][sml]] - TODO
+ [[file:../modules/lang/solidity/README.org][solidity]] - TODO
+ swift =+lsp= - TODO
+ terra - TODO
+ web =+lsp= - HTML and CSS (SCSS/SASS/LESS/Stylus) support.
+ [[file:../modules/lang/yaml/README.org][yaml]] =+lsp= - TODO
+ [[file:../modules/lang/zig/README.org][zig]] =+lsp= - Zig support.
* :os
Modules to improve integration into your OS, system, or devices.
+ [[file:../modules/os/macos/README.org][macos]] - Improve Emacs' compatibility with macOS
+ [[file:../modules/os/tty/README.org][tty]] =+osc= - Improves the terminal Emacs experience.
* :term
Modules that offer terminal emulation.
+ [[file:../modules/term/eshell/README.org][eshell]] - TODO
+ shell - TODO
+ term - TODO
+ [[file:../modules/term/vterm/README.org][vterm]] - TODO
* :tools
Small modules that give Emacs access to external tools & services.
+ ansible - TODO
+ debugger =+lsp= - A (nigh-)universal debugger in Emacs
+ [[file:../modules/tools/direnv/README.org][direnv]] - TODO
+ [[file:../modules/tools/docker/README.org][docker]] =+lsp= - TODO
+ [[file:../modules/tools/editorconfig/README.org][editorconfig]] - TODO
+ [[file:../modules/tools/ein/README.org][ein]] - TODO
+ [[file:../modules/tools/eval/README.org][eval]] =+overlay= - REPL & code evaluation support for a variety of languages
+ gist - TODO
+ [[file:../modules/tools/lookup/README.org][lookup]] =+dictionary +docsets +offline= - Universal jump-to & documentation lookup
backend
+ [[file:../modules/tools/lsp/README.org][lsp]] =+peek +eglot= - Installation and configuration of language server protocol client (lsp-mode or eglot)
+ [[file:../modules/tools/magit/README.org][magit]] =+forge= - TODO
+ make - TODO
+ [[file:../modules/tools/pass/README.org][pass]] =+auth= - TODO
+ [[file:../modules/tools/pdf/README.org][pdf]] - TODO
+ prodigy - TODO
+ [[file:../modules/tools/rgb/README.org][rgb]] - TODO
+ [[file:../modules/tools/taskrunner/README.org][taskrunner]] - TODO
+ [[file:../modules/tools/terraform/README.org][terraform]] - TODO
+ tmux - TODO
+ [[file:../modules/tools/tree-sitter/README.org][tree-sitter]] - syntax and parsing, sitting in a tree...
+ [[file:../modules/tools/upload/README.org][upload]] - TODO
* :ui
Aesthetic modules that affect the Emacs interface or user experience.
+ [[file:../modules/ui/deft/README.org][deft]] - TODO
+ [[file:../modules/ui/doom/README.org][doom]] - TODO
+ [[file:../modules/ui/doom-dashboard/README.org][doom-dashboard]] - TODO
+ [[file:../modules/ui/doom-quit/README.org][doom-quit]] - TODO
+ [[file:../modules/ui/emoji/README.org][emoji]] =+ascii +github +unicode= - Adds emoji support to Emacs
+ [[file:../modules/ui/hl-todo/README.org][hl-todo]] - TODO
+ [[file:../modules/ui/hydra/README.org][hydra]] - TODO
+ indent-guides - TODO
+ [[file:../modules/ui/ligatures/README.org][ligatures]] =+extra +fira +hasklig +iosevka +pragmata-pro= - Ligature support for Emacs
+ [[file:../modules/ui/minimap/README.org][minimap]] - TODO
+ [[file:../modules/ui/modeline/README.org][modeline]] =+light= - TODO
+ [[file:../modules/ui/nav-flash/README.org][nav-flash]] - TODO
+ [[file:../modules/ui/neotree/README.org][neotree]] - TODO
+ [[file:../modules/ui/ophints/README.org][ophints]] - TODO
+ [[file:../modules/ui/popup/README.org][popup]] =+all +defaults= - Makes temporary/disposable windows less intrusive
+ [[file:../modules/ui/tabs/README.org][tabs]] - TODO
+ [[file:../modules/ui/treemacs/README.org][treemacs]] - =+lsp= - A tree layout file explorer for Emacs
+ [[file:../modules/ui/unicode/README.org][unicode]] - TODO
+ vc-gutter - TODO
+ vi-tilde-fringe - TODO
+ [[file:../modules/ui/window-select/README.org][window-select]] =+switch-window +numbers= - TODO
+ [[file:../modules/ui/workspaces/README.org][workspaces]] - Isolated workspaces
+ [[file:../modules/ui/zen/README.org][zen]] - Distraction-free coding (or writing)

2
lisp/doom-editor.el
View file

@ -1,7 +1,7 @@
;;; doom-editor.el -*- lexical-binding: t; -*-
(defvar doom-detect-indentation-excluded-modes
'(fundamental-mode pascal-mode so-long-mode)
'(fundamental-mode pascal-mode so-long-mode doom-docs-org-mode)
"A list of major modes in which indentation should be automatically
detected.")

624
lisp/lib/docs.el Normal file
View file

@ -0,0 +1,624 @@
;;; core/lib/docs.el -- a reader mode for Doom's Org docs -*- lexical-binding: t; -*-
;;; Commentary:
;;; Code:
(defvar doom-docs-header-alist
`(("/docs/index\\.org$"
(left ("↖ FAQ" . "doom-faq:")))
(("/docs/[^/]+\\.org$" "/modules/README\\.org$")
(left ("← Back to index" . "doom-index:")))
("/modules/[^/]+/README\\.org$"
(left ("← Back to module index" . "doom-module-index:")))
("/modules/[^/]+/[^/]+/README\\.org$"
(left ("← Back to module index" . "doom-module-index:"))
(right ("↖ History"
. ,(lambda (file)
(cl-destructuring-bind (category . module) (doom-module-from-path file)
(format "doom-module-history:%s/%s" (doom-keyword-name category) module))))
("! Issues"
. ,(lambda (file)
(cl-destructuring-bind (category . module) (doom-module-from-path file)
(format "doom-module-issues::%s %s" category module)))))))
"TODO")
(defvar doom-docs-header-common-alist
`(("± Suggest edits" . "doom-suggest-edit:")
("? Help"
. ,(lambda (_file)
(let ((title (cadar (org-collect-keywords '("TITLE")))))
(cond ((equal title "Changelog") "doom-help-changelog:")
((string-prefix-p ":" title) "doom-help-modules:")
("doom-help:"))))))
"TODO")
;;
;;; `doom-docs-mode'
(defun doom-docs--display-header-h ()
"Show header line in Doom documentation."
(let ((beg (point-min))
end)
(org-with-wide-buffer
(goto-char beg)
(when (looking-at-p "^# -\\*- ")
(goto-char (line-beginning-position 2))
(setq beg (point)))
(when (looking-at-p org-drawer-regexp)
(re-search-forward org-drawer-regexp nil t 2)
(goto-char (setq beg (1+ (line-end-position)))))
(with-silent-modifications
(let ((inhibit-modification-hooks nil)
(menu (cl-loop for (regexp . rules) in doom-docs-header-alist
if (seq-find (doom-rpartial #'string-match-p (buffer-file-name))
(ensure-list regexp))
return rules)))
(when (re-search-forward "^-\\{80\\}" 512 t)
(delete-region beg (1+ (line-end-position))))
(when (and menu doom-docs-mode)
(let* ((fn
(lambda (menu)
(cl-destructuring-bind (icon . label)
(split-string (car menu) " ")
(if (cdr menu)
(format "%s [[%s][%s]]"
icon
(cond ((functionp (cdr menu))
(funcall (cdr menu) (buffer-file-name)))
((file-name-absolute-p (cdr menu))
(concat "file:"
(file-relative-name (file-truename (cdr menu)))))
((cdr menu)))
(string-join label " "))
(format "%s+ %s+" icon (string-join label " "))))))
(lenfn
(lambda (link)
(length (replace-regexp-in-string org-link-any-re "\\3" link))))
(sep " ")
(lhs (mapconcat fn (alist-get 'left menu) sep))
(rhs (mapconcat fn (append (alist-get 'right menu)
doom-docs-header-common-alist)
sep))
(llen (funcall lenfn lhs))
(rlen (funcall lenfn rhs))
(pad (max 0 (- 80 llen rlen))))
(insert lhs
(if (zerop rlen) ""
(format "%s%s" (make-string pad 32) rhs))
"\n" (make-string 80 ?-) "\n")))))
(org-element-cache-refresh (point-min)))))
(defun doom-docs--hide-meta-h ()
"Hide all meta or comment lines."
(org-with-wide-buffer
(goto-char (point-min))
(save-match-data
(let ((case-fold-search t))
(while (re-search-forward "^[ \t]*\\#" nil t)
(catch 'abort
(org-fold-core-region
(line-beginning-position)
(cond ((looking-at "+\\(?:title\\|subtitle\\): +")
(match-end 0))
((looking-at "+\\(?:created\\|since\\|author\\|email\\|date\\): +")
(throw 'abort nil))
((or (eq (char-after) ?\s)
(looking-at "+\\(begin\\|end\\)_comment"))
(line-beginning-position 2))
((looking-at "+\\(?:begin\\|end\\)_\\([^ \n]+\\)")
(line-end-position))
((line-beginning-position 2)))
doom-docs-mode 'doom-doc-hidden)))))))
(defun doom-docs--hide-drawers-h ()
"Hide all property drawers."
(org-with-wide-buffer
(goto-char (point-min))
(while (re-search-forward org-drawer-regexp nil t)
(let ((beg (max (point-min) (1- (match-beginning 0))))
(end (re-search-forward org-drawer-regexp nil t)))
(unless (org-current-level)
(cl-incf end))
(org-fold-core-region beg end doom-docs-mode 'doom-doc-hidden)))))
(defun doom-docs--hide-tags-h ()
"Hide tags in org headings."
(org-with-wide-buffer
(goto-char (point-min))
(while (re-search-forward org-heading-regexp nil t)
(when-let (tags (org-get-tags nil t))
(when (or (member "noorg" tags)
(member "unfold" tags))
;; prevent `org-ellipsis' around hidden regions
(org-show-entry))
(if (member "noorg" tags)
(org-fold-core-region (line-end-position 0)
(save-excursion
(org-end-of-subtree t)
(forward-line 1)
(if (and (bolp) (eolp))
(line-beginning-position)
(line-end-position 0)))
doom-docs-mode 'doom-doc-hidden)
(org-fold-core-region (save-excursion
(goto-char (line-beginning-position))
(re-search-forward " +:[^ ]" (line-end-position))
(match-beginning 0))
(line-end-position)
doom-docs-mode 'doom-doc-hidden))))))
(defun doom-docs--hide-stars-h ()
"Update invisible property to VISIBILITY for markers in the current buffer."
(org-with-wide-buffer
(goto-char (point-min))
(with-silent-modifications
(while (re-search-forward "^\\(\\*[ \t]\\|\\*\\*+\\)" nil t)
(org-fold-core-region (match-beginning 0)
(match-end 0)
doom-docs-mode
'doom-doc-hidden)))))
(defvar doom-docs--babel-cache nil)
(defun doom-docs--hide-src-blocks-h ()
"Hide babel blocks (and/or their results) depending on their :exports arg."
(org-with-wide-buffer
(let ((inhibit-read-only t))
(goto-char (point-min))
(make-local-variable 'doom-docs--babel-cache)
(while (re-search-forward org-babel-src-block-regexp nil t)
(let* ((beg (match-beginning 0))
(end (save-excursion (goto-char (match-end 0))
(skip-chars-forward "\n")
(point)))
(exports
(save-excursion
(goto-char beg)
(and (re-search-forward " :exports \\([^ \n]+\\)" (line-end-position) t)
(match-string-no-properties 1))))
(results (org-babel-where-is-src-block-result)))
(save-excursion
(when (and (if (stringp exports)
(member exports '("results" "both"))
org-export-use-babel)
(not results)
doom-docs-mode)
(cl-pushnew beg doom-docs--babel-cache)
(quiet! (org-babel-execute-src-block))
(setq results (org-babel-where-is-src-block-result))
(org-element-cache-refresh beg)
(restore-buffer-modified-p nil)))
(save-excursion
(when results
(when (member exports '("code" "both" "t"))
(setq beg results))
(when (member exports '("none" "code"))
(setq end (progn (goto-char results)
(goto-char (org-babel-result-end))
(skip-chars-forward "\n")
(point))))))
(unless (member exports '(nil "both" "code" "t"))
(org-fold-core-region beg end doom-docs-mode 'doom-doc-hidden))))
(unless doom-docs-mode
(save-excursion
(dolist (pos doom-docs--babel-cache)
(goto-char pos)
(org-babel-remove-result)
(org-element-cache-refresh pos))
(kill-local-variable 'doom-docs--babel-cache)
(restore-buffer-modified-p nil))))))
(defvar doom-docs--macro-cache nil)
(defun doom-docs--expand-macros-h ()
"Expand {{{macros}}} with their value."
(org-with-wide-buffer
(goto-char (point-min))
(make-local-variable 'doom-docs--macro-cache)
(while (re-search-forward "{{{[^}]+}}}" nil t)
(with-silent-modifications
(if doom-docs-mode
(when-let* ((element (org-element-context))
(key (org-element-property :key element))
(cachekey (org-element-property :value element))
(template (cdr (assoc-string key org-macro-templates t))))
(let ((value (or (cdr (assoc-string cachekey doom-docs--macro-cache))
(setf (alist-get cachekey doom-docs--macro-cache nil nil 'equal)
(org-macro-expand element org-macro-templates)))))
(add-text-properties (match-beginning 0)
(match-end 0)
`(display ,value))))
(remove-text-properties (match-beginning 0)
(match-end 0)
'(display))))
(org-element-cache-refresh (point)))))
(defvar doom-docs-mode-alist
'((flyspell-mode . -1)
(spell-fu-mode . -1)
(visual-line-mode . -1)
(mixed-pitch-mode . -1)
(variable-pitch-mode . -1))
"An alist of minor modes to activate or deactivate in `doom-docs-mode'.
The CAR is the minor mode symbol, and CDR should be either +1 or -1,
depending.")
(defvar doom-docs--initial-values nil)
(defvar doom-docs--cookies nil)
;;;###autoload
(define-minor-mode doom-docs-mode
"Hides metadata, tags, & drawers and activates all org-mode pretiffications.
This primes `org-mode' for reading."
:lighter " Doom Docs"
:after-hook (org-restart-font-lock)
(unless (derived-mode-p 'org-mode)
(user-error "Not an org mode buffer"))
(org-fold-add-folding-spec
'doom-doc-hidden '(:visible nil
:alias (hidden)
:isearch-open nil
:font-lock-skip t))
(mapc (lambda (sym)
(if doom-docs-mode
(set (make-local-variable sym) t)
(kill-local-variable sym)))
`(org-pretty-entities
org-hide-emphasis-markers
org-hide-macro-markers))
(when doom-docs-mode
(make-local-variable 'doom-docs--initial-values))
(mapc (lambda! ((face . plist))
(if doom-docs-mode
(push (apply #'face-remap-add-relative face plist) doom-docs--cookies)
(mapc #'face-remap-remove-relative doom-docs--cookies)))
'((org-document-title :weight bold :height 1.4)
(org-document-info :weight normal :height 1.15)))
(mapc (lambda! ((mode . state))
(if doom-docs-mode
(if (and (boundp mode) (symbol-value mode))
(unless (> state 0)
(setf (alist-get mode doom-docs--initial-values) t)
(funcall mode -1))
(unless (< state 0)
(setf (alist-get mode doom-docs--initial-values) nil)
(funcall mode +1)))
(when-let (old-val (assq mode doom-docs--initial-values))
(funcall mode (if old-val +1 -1)))))
doom-docs-mode-alist)
(unless doom-docs-mode
(kill-local-variable 'doom-docs--initial-values)))
(add-hook! 'doom-docs-mode-hook
#'doom-docs--display-header-h
#'doom-docs--hide-meta-h
#'doom-docs--hide-tags-h
#'doom-docs--hide-drawers-h
#'doom-docs--hide-stars-h
#'doom-docs--expand-macros-h
#'doom-docs--hide-src-blocks-h)
(defun doom-docs--toggle-read-only-h ()
(doom-docs-mode (if buffer-read-only +1 -1)))
(defvar doom-docs--id-locations nil)
(defvar doom-docs--id-files nil)
;;;###autoload
(defun doom/reload-docs (&optional force)
"Reload the ID locations in Doom's documentation and open docs buffers."
(interactive (list 'interactive))
(with-temp-buffer
(let ((org-id-locations-file
(doom-path (file-truename doom-cache-dir) "doom-docs-org-ids"))
(org-id-track-globally t)
org-agenda-files
org-id-extra-files
org-id-files
org-id-locations
org-id-extra-files
(org-inhibit-startup t)
org-mode-hook)
(if force
(org-id-update-id-locations
(doom-files-in (list doom-docs-dir doom-modules-dir)
:match "/[^.].+\\.org$"))
(org-id-locations-load))
(setq doom-docs--id-files org-id-files
doom-docs--id-locations org-id-locations)))
(dolist (buf (doom-buffers-in-mode 'doom-docs-org-mode))
(with-current-buffer buf
(setq-local org-id-files doom-docs--id-files
org-id-locations doom-docs--id-locations))))
;;
;;; `doom-docs-org-mode'
(defvar doom-docs-link-alist
'(("doom-tag" . "https://github.com/hlissner/doom-emacs/releases/tag/%s")
("doom-contrib-core" . "id:9ac0c15c-29e7-43f8-8926-5f0edb1098f0")
("doom-contrib-docs" . "id:31f5a61d-d505-4ee8-9adb-97678250f4e2")
("doom-contrib-maintainer" . "id:e71e9595-a297-4c49-bd11-f238329372db")
("doom-contrib-module" . "id:b461a050-8702-4e63-9995-c2ef3a78f35d")
("doom-faq" . "id:5fa8967a-532f-4e0c-8ae8-25cd802bf9a9")
("doom-help" . "id:9bb17259-0b07-45a8-ae7a-fc5e0b16244e")
("doom-help-changelog" . "id:7c56cc08-b54b-4f4b-b106-a76e2650addd")
("doom-help-modules" . "id:1ee0b650-f09b-4454-8690-cc145aadef6e")
("doom-index" . "id:3051d3b6-83e2-4afa-b8fe-1956c62ec096")
("doom-module-index" . "id:12d2de30-c569-4b8e-bbc7-85dd5ccc4afa")
("doom-module-issues" . "https://github.com/doomemacs/doomemacs/labels/%s")
("doom-module-history" . "https://github.com/doomemacs/doomemacs/commits/master/modules/%s")
("doom-report" . "https://github.com/doomemacs/doomemacs/issues/new/choose")
("doom-suggest-edit" . "id:31f5a61d-d505-4ee8-9adb-97678250f4e2")
("doom-suggest-faq" . "id:aa28b732-0512-49ed-a47b-f20586c0f051")
("github" . "https://github.com/%s")))
;;;###autoload
(define-derived-mode doom-docs-org-mode org-mode "Doom Docs"
"A derivative of `org-mode' for Doom's documentation files.
Keeps track of its own IDs in `doom-docs-dir' and toggles `doom-docs-mode' when
`read-only-mode' is activated."
:after-hook (visual-line-mode -1)
(require 'org-id)
(require 'ob)
(setq-local org-id-link-to-org-use-id t
org-id-method 'uuid
org-id-track-globally t
org-id-locations-file (doom-path doom-cache-dir "doom-docs-org-ids")
org-id-locations doom-docs--id-locations
org-id-files doom-docs--id-files
org-num-max-level 3
org-footnote-define-inline nil
org-footnote-auto-label t
org-footnote-auto-adjust t
org-footnote-section nil
wgrep-change-readonly-file t
org-link-abbrev-alist-local (append org-link-abbrev-alist-local doom-docs-link-alist)
org-babel-default-header-args
(append '((:eval . "no") (:tangle . "no"))
org-babel-default-header-args)
save-place-ignore-files-regexp ".")
(when (require 'org-glossary nil t)
(setq org-glossary-collection-root doom-docs-dir
org-glossary-global-terms (doom-glob org-glossary-collection-root "appendix.org"))
(require 'ox)
(org-glossary-mode +1))
(unless org-inhibit-startup
(doom/reload-docs)
(unless (local-variable-p 'org-startup-with-inline-images)
(setq org-display-remote-inline-images 'cache)
(org-display-inline-images))
(unless (local-variable-p 'org-startup-indented)
(org-indent-mode +1))
(unless (local-variable-p 'org-startup-numerated)
(when (bound-and-true-p org-num-mode)
(org-num-mode -1))
(org-num-mode +1))
(unless (local-variable-p 'org-startup-folded)
(let ((org-startup-folded 'content))
(org-set-startup-visibility))))
(add-hook 'read-only-mode-hook #'doom-docs--toggle-read-only-h nil 'local)
(org-with-limited-levels
(end-of-line)
(null (re-search-forward org-outline-regexp-bol nil t))))
;;;###autoload
(defun doom-docs-read-only-h ()
"Activate `read-only-mode' if the current file exists and is non-empty."
;; The rationale: if it's empty or non-existant, you want to write an org
;; file, not read it.
(let ((file-name (buffer-file-name (buffer-base-buffer))))
(when (and file-name
(> (buffer-size) 0)
(not (string-prefix-p "." (file-name-base file-name)))
(file-exists-p file-name))
(read-only-mode +1))))
(add-hook 'doom-docs-org-mode-hook #'doom-docs-read-only-h)
;;
;;; Custom links
;;;###autoload
(defun doom-docs-read-link-desc-at-point (&optional default context)
"TODO"
(if (and (stringp default) (not (string-empty-p default)))
(string-trim default)
(if-let* ((context (or context (org-element-context)))
(context (org-element-lineage context '(link) t))
(beg (org-element-property :contents-begin context))
(end (org-element-property :contents-end context)))
(unless (= beg end)
(replace-regexp-in-string
"[ \n]+" " " (string-trim (buffer-substring-no-properties beg end)))))))
;;;###autoload
(defun doom-docs-doom-module-link-follow-fn (link)
(cl-destructuring-bind (&key category module flag)
(doom-docs--read-module-link link)
(when category
(let ((doom-modules-dirs (list doom-modules-dir)))
(if-let* ((path (doom-module-locate-path category module))
(path (or (car (doom-glob path "README.org"))
path)))
(find-file path)
(user-error "Can't find Doom module '%s'" link))))
(when flag
(goto-char (point-min))
(when (and (re-search-forward "^\\*+ \\(?:TODO \\)?Module flags")
(re-search-forward (format "^\\s-*- \\+%s ::[ \n]"
(substring (symbol-name flag) 1))
(save-excursion (org-get-next-sibling)
(point))))
(org-show-entry)
(recenter)))))
;;;###autoload
(defun doom-docs-doom-module-link-face-fn (link)
(cl-destructuring-bind (&key category module flag)
(doom-docs--read-module-link link)
(if (doom-module-locate-path category module)
`(:inherit org-priority
:weight bold)
'error)))
;;;###autoload
(defun doom-docs-doom-package-link-follow-fn (link)
"TODO"
(doom/describe-package
(intern-soft
(doom-docs-read-link-desc-at-point link))))
;;;###autoload
(defun doom-docs-make-symbol-link (fn)
"TODO"
(lambda (link)
(let ((desc (doom-docs-read-link-desc-at-point link)))
(funcall
fn (or (intern-soft desc)
(user-error "Can't find documentation for %S" desc))))))
(defun doom-docs--describe-kbd (keystr)
(dolist (key `(("<leader>" . ,doom-leader-key)
("<localleader>" . ,doom-localleader-key)
("<prefix>" . ,(if (bound-and-true-p evil-mode)
(concat doom-leader-key " u")
"C-u"))
("<help>" . ,(if (bound-and-true-p evil-mode)
(concat doom-leader-key " h")
"C-h"))
("\\<M-" . "alt-")
("\\<S-" . "shift-")
("\\<s-" . "super-")
("\\<C-" . "ctrl-")))
(setq keystr
(replace-regexp-in-string (car key) (cdr key)
keystr t t)))
keystr)
;;;###autoload
(defun doom-docs-read-kbd-at-point (&optional default context)
"TODO"
(doom-docs--describe-kbd
(doom-docs-read-link-desc-at-point default context)))
;;;###autoload
(after! org
;; Add "lookup" links for packages and keystrings; useful for Emacs
;; documentation -- especially Doom's!
(org-link-set-parameters
"kbd"
:follow (lambda (_) (minibuffer-message "%s" (doom--display-docs-link-in-eldoc-a)))
:help-echo #'doom-docs-read-kbd-at-point
:face 'help-key-binding)
(org-link-set-parameters
"var"
:follow (doom-docs-make-symbol-link #'helpful-variable)
:face '(font-lock-variable-name-face underline))
(org-link-set-parameters
"fn"
:follow (doom-docs-make-symbol-link #'helpful-callable)
:face '(font-lock-function-name-face underline))
(org-link-set-parameters
"face"
:follow (doom-docs-make-symbol-link #'describe-face)
:face '(font-lock-type-face underline))
(org-link-set-parameters
"doom-ref"
:follow (lambda (link)
(let ((link (doom-docs-read-link-desc-at-point link))
(url "https://github.com")
(doom-repo "doomemacs/doomemacs"))
(save-match-data
(browse-url
(cond ((string-match "^\\([^/]+\\(?:/[^/]+\\)?\\)?#\\([0-9]+\\(?:#.*\\)?\\)" link)
(format "%s/%s/issues/%s" url
(or (match-string 1 link)
doom-repo)
(match-string 2 link)))
((string-match "^\\([^/]+\\(?:/[^/]+\\)?@\\)?\\([a-z0-9]\\{7,\\}\\(?:#.*\\)?\\)" link)
(format "%s/%s/commit/%s" url
(or (match-string 1 link)
doom-repo)
(match-string 2 link)))
((user-error "Invalid doom-ref link: %S" link)))))))
:face (lambda (link)
(let ((link (doom-docs-read-link-desc-at-point link)))
(if (or (string-match "^\\([^/]+\\(?:/[^/]+\\)?\\)?#\\([0-9]+\\(?:#.*\\)?\\)" link)
(string-match "^\\([^/]+\\(?:/[^/]+\\)?@\\)?\\([a-z0-9]\\{7,\\}\\(?:#.*\\)?\\)" link))
'org-link
'error))))
(org-link-set-parameters
"doom-user"
:follow (lambda (link)
(browse-url
(format "https://github.com/%s"
(string-remove-prefix
"@" (doom-docs-read-link-desc-at-point link)))))
:face (lambda (_) 'org-priority))
(org-link-set-parameters
"doom-package"
:follow #'doom-docs-doom-package-link-follow-fn
:face (lambda (_) '(:inherit org-priority :slant italic)))
(org-link-set-parameters
"doom-source"
:follow (lambda (link)
(user-error "-- %S %S %S" source url link)
(cl-destructuring-bind (source . url)
(save-match-data
(and (string-match "^\\([^:]+\\):\\(.+\\)$" link)
(cons (match-string 1) (match-string 2))))
(pcase source
("doom"
(org-link-open (expand-file-name url doom-modules-dir)))
("contrib"
(browse-url (format "https://docs.doomemacs.org/modules/"
(replace-regexp-in-string "::\\(.+\\)$" "#\\1" url))))
(_ (user-error "%s is not a valid module source" source))))))
(org-link-set-parameters
"doom-module"
:follow #'doom-docs-doom-module-link-follow-fn
:face #'doom-docs-doom-module-link-face-fn)
(org-link-set-parameters
"doom-changelog"
:follow (lambda (link)
(find-file (doom-path doom-docs-dir "changelog.org"))
(org-match-sparse-tree nil link)))
(add-to-list 'org-link-abbrev-alist '("doom-repo" . "https://github.com/doomemacs/doomemacs/%s"))
(defadvice! doom--display-docs-link-in-eldoc-a (&rest _)
"Display full doom-*: links in minibuffer when cursor/mouse is over it."
:before-until #'org-eldoc-documentation-function
(when-let* ((context (org-element-context))
(path (org-element-property :path context)))
(pcase (org-element-property :type context)
("kbd"
(format "%s %s"
(propertize "Key sequence:" 'face 'bold)
(propertize (doom-docs-read-kbd-at-point path context)
'face 'help-key-binding)))
("doom-module"
(format "%s %s"
(propertize "Doom module:" 'face 'bold)
(propertize (doom-docs-read-link-desc-at-point path)
'face 'org-priority)))
("doom-package"
(format "%s %s"
(propertize "Doom package:" 'face 'bold)
(propertize (doom-docs-read-link-desc-at-point path)
'face 'org-priority)))))))
(defun doom-docs--read-module-link (link)
(cl-destructuring-bind (category &optional module flag)
(let ((desc (doom-docs-read-link-desc-at-point link)))
(if (string-prefix-p "+" (string-trim-left desc))
(list nil nil (intern desc))
(mapcar #'intern (split-string desc " " nil))))
(list :category category
:module module
:flag flag)))
;;; docs.el ends here

1
lisp/lib/help.el
View file

@ -749,3 +749,4 @@ Uses the symbol at point or the current selection, if available."
(format "%s.el" filebase)))
collect it)
query "Search loaded files: "))

1492
modules/README.org Normal file
View file

File diff suppressed because it is too large Load diff

12
modules/app/README.org Normal file
View file

@ -0,0 +1,12 @@
# -*- mode: doom-docs-org -*-
#+title: :app
#+created: February 19, 2017
#+since: 21.12.0
* Description
Application modules are complex and opinionated modules that transform Emacs
toward a specific purpose. They may have additional dependencies and *should be
loaded last* (but before [[doom-module:][:config]] modules).
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

73
modules/app/calendar/README.org
View file

@ -1,34 +1,52 @@
#+TITLE: app/calendar
#+DATE: January 13, 2018
#+SINCE: v2.1
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :app calendar
#+subtitle: Watch your missed deadlines in real time
#+created: January 13, 2018
#+since: 21.12.0 (#355)
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#packages][Packages]]
- [[#configuration][Configuration]]
- [[#changing-calendar-sources][Changing calendar sources]]
- [[#synchronizing-org-and-google-calendar][Synchronizing Org and Google Calendar]]
* Description
* Description :unfold:
This module adds a calendar view for Emacs, with org and google calendar sync
support.
** Module Flags
This module provides no flags.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
+ [[https://github.com/kiwanami/emacs-calfw][calfw]]
+ [[https://github.com/kiwanami/emacs-calfw][calfw-org]]
+ [[https://github.com/kidd/org-gcal.el][org-gcal]]
- [[doom-package:][calfw]]
- [[doom-package:][calfw-org]]
- [[doom-package:][org-gcal]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- A Google Calendar account.
- [[https://github.com/kidd/org-gcal.el#installation][An OAuth client ID]], for syncing said account with [[doom-package:][org-gcal]].
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Changing calendar sources
By defining your own calendar commands, you can control what sources to pull
calendar data from:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(defun my-open-calendar ()
(interactive)
(cfw:open-calendar-buffer
@ -41,10 +59,21 @@ calendar data from:
(cfw:ical-create-source "Moon" "~/moon.ics" "Gray") ; ICS source1
(cfw:ical-create-source "gcal" "https://..../basic.ics" "IndianRed") ; google calendar ICS
)))
#+END_SRC
#+end_src
The [[https://github.com/kiwanami/emacs-calfw][kiwanami/emacs-calfw]] project readme contains more examples.
** Synchronizing Org and Google Calendar
The [[https://github.com/kidd/org-gcal.el][kidd/org-gcal.el]] project README contains more detailed instructions on how
to link your calendar with Google calendars.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

118
modules/app/emms/README.org
View file

@ -1,71 +1,75 @@
#+TITLE: app/emms
#+DATE: March 6, 2021
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :app emms
#+subtitle: A media player for music no one's heard of
#+created: March 06, 2021
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#arch-linux][Arch Linux]]
- [[#nixos][NixOS]]
- [[#ubuntu][Ubuntu]]
- [[#troubleshooting][Troubleshooting]]
- [[#new-music-files-not-showing-up-in-database][New music files not showing up in database]]
- [[#appendix][Appendix]]
- [[#keybinds][Keybinds]]
* Description
* Description :unfold:
This module enables Emacs to be used as a music player. It uses [[https://www.musicpd.org/][mpd]] as a backend
server and [[https://musicpd.org/clients/mpc/][mpc]] to update your music database.
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
+ [[https://git.savannah.gnu.org/git/emms.git/][emms]]
** Packages
- [[doom-package:][emms]]
* Prerequisites
This module requires an active MPD server, the MPC utility, and a music library.
** Hacks
/No hacks documented for this module./
** Arch Linux
#+BEGIN_SRC bash
pacman -S mpd mpc
#+END_SRC
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
** NixOS
#+BEGIN_SRC nix
services.mpd.enable = true;
environment.systemPackages = [ pkgs.mpc_cli ];
#+END_SRC
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
** Ubuntu
#+BEGIN_SRC bash
apt install mpd mpc
#+END_SRC
This module requires:
- [[https://mpd.readthedocs.io/en/stable/user.html#installation][mpd]] (and a running mpd server)
- [[https://www.musicpd.org/clients/mpc/][mpc]]
These should be available through your OS package manager.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Keybinds
- [[kbd:][<localleader> l]] Toggles whether or not the player repeats the playlist.
- [[kbd:][<localleader> m]] Mixes the playlist.
- [[kbd:][<localleader> i]] Insert specific song
- [[kbd:][<localleader> s]] Save the current playlist to a file
- [[kbd:][<localleader> p]] Insert playlist save into current playlist
- [[kbd:][g a]] Sort the browser by artists
- [[kbd:][g b]] Sort the browser by genre
- [[kbd:][X]] Stops the player
- [[kbd:][x]] pauses the player
- [[kbd:][D]] in the playlist window removes that item
- [[kbd:][C]] clears the playlist
- [[kbd:][>]] move five seconds forward in the current track
- [[kbd:][<]] Opposite five back
- [[kbd:][RET]] In browser adds the artist's songs to the playlist, in the playlist starts
playlist.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
** New music files not showing up in database
Try =M-x +emms/mpd-restart-music-daemon=. If that doesn't work restart emacs.
[[doom-report:][Report an issue?]]
* Appendix
** Keybinds
+ =SPC m l= Toggles whether or not the player repeats the playlist.
+ =SPC m m= Mixes the playlist.
+ =SPC m i= Insert specific song
+ =SPC m s= Save the current playlist to a file
+ =SPC m p= Insert playlist save into current playlist
+ =g a= Sort the browser by artists
+ =g b= Sort the browser by genre
+ =X= Stops the player
+ =x= pauses the player
+ =D= in the playlist window removes that item
+ =C= clears the playlist
+ =>= move five seconds forward in the current track
+ =<= Opposite five back
+ =RET= In browser adds the artist's songs to the playlist, in the playlist starts playlist.
** New music files not showing up in database
Try [[kbd:][M-x +emms/mpd-restart-music-daemon]] then restart emacs.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

81
modules/app/everywhere/README.org
View file

@ -1,58 +1,73 @@
#+title: app/everywhere
#+date: February 7, 2021
#+since: v3.0
#+startup: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :app everywhere
#+subtitle: *leave* Emacs!? You must be joking
#+created: February 07, 2021
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
* Description
* Description :unfold:
This module adds system-wide popup Emacs windows for quick edits.
** Maintainers
+ [[https://github.com/tecosaur][@tecosaur]]
- [[doom-user:][@tecosaur]]
** Module Flags
[[doom-contrib-maintainer:][Become a maintainer?]]
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
+ [[https://github.com/tecosaur/emacs-everywhere][emacs-everywhere]]
** Packages
- [[doom-package:][emacs-everywhere]]
* Prerequisites
** Hacks
/No hacks documented for this module./
On Linux =xclip=, =xdotool=, =xprop=, and =xwininfo= are needed.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
On MacOS, Emacs must be allowed to "control your computer" under *Settings > Accessibility*.
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Features
This module requires:
- *On Linux:* (these should be available through your OS package manager)
- =xclip=
- =xdotool=
- =xprop=
- =xwininfo=
- *On MacOS:* that Emacs is allowed to "control your computer" under *System
Preferences > Accessibility*.
* Usage
To use this, invoke the =emacs-everywhere= executable. This can be done in two
ways:
+ ~emacsclient --eval "(emacs-everywhere)"~
+ ~doom everywhere~
+ ~$ emacsclient --eval "(emacs-everywhere)"~
+ ~$ doom everywhere~
It is recommended that you add a keybinding for this.
From here, you can edit away to your hearts content in the created frame, then
return to the original window and paste the content with =C-c C-c= or =SPC q f=.
To exit without pasting, use =C-c C-k=.
return to the original window and paste the content with [[kbd:][C-c C-c]] or [[kbd:][SPC q f]]. To
exit without pasting, use [[kbd:][C-c C-k]].
* Configuration
=emacs-everywhere= likes to guess if you triggered it from an application which
[[doom-package:][emacs-everywhere]] likes to guess if you triggered it from an application which
supports markdown. Configure ~emacs-everywhere-markdown-windows~ and
~emacs-everywhere-markdown-apps~ to improve how accurate this is on your system.
By default, when markdown is detected, ~markdown-mode~ is used. It is possible to
instead use pandoc to convert the content to Org (and export to markdown when
By default, when markdown is detected, ~markdown-mode~ is used. It is possible
to instead use pandoc to convert the content to Org (and export to markdown when
closing the frame) by setting ~emacs-everywhere-major-mode-function~ to
=#'org-mode=.
~#'org-mode~.
Most other behaviour is implemented as hooks on ~emacs-everywhere-init-hooks~.
Most other behavior is implemented as hooks on ~emacs-everywhere-init-hooks~.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

156
modules/app/irc/README.org
View file

@ -1,82 +1,82 @@
#+TITLE: app/irc
#+DATE: June 11, 2017
#+SINCE: v2.0.3
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :app irc
#+subtitle: How neckbeards socialize
#+created: June 11, 2017
#+since: 2.0.3
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#macos][macOS]]
- [[#debian--ubuntu][Debian / Ubuntu]]
- [[#arch-linux][Arch Linux]]
- [[#nixos][NixOS]]
- [[#features][Features]]
- [[#an-irc-client-in-emacs][An IRC Client in Emacs]]
- [[#configuration][Configuration]]
- [[#pass-the-unix-password-manager][Pass: the unix password manager]]
- [[#emacs-auth-source-api][Emacs' auth-source API]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module turns Emacs into an IRC client, capable of OS notifications.
** Module Flags
This module provides no flags.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/jorgenschaefer/circe][circe]]
+ [[https://github.com/eqyiel/circe-notifications][circe-notifications]]
** Module flags
/This module has no flags./
* Prerequisites
This module requires =gnutls= for secure IRC connections to work.
** Packages
- [[doom-package:][circe]]
- [[doom-package:][circe-notifications]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- [[https://www.gnutls.org/][GnuTLS]], for secure IRC connections to work.
This should be available through your OS package manager.
** macOS
#+BEGIN_SRC sh
#+begin_src sh
brew install gnutls
#+END_SRC
#+end_src
** Debian / Ubuntu
#+BEGIN_SRC sh
#+begin_src sh
apt install gnutls-bin
#+END_SRC
#+end_src
** Arch Linux
#+BEGIN_SRC sh
#+begin_src sh
pacman -S gnutls
#+END_SRC
#+end_src
** NixOS
#+BEGIN_SRC nix
#+begin_src nix
environment.systemPackages = [ pkgs.gnutls ];
#+END_SRC
#+end_src
* Features
** An IRC Client in Emacs
To connect to IRC you can invoke the ~=irc~ function using =M-x= or your own
custom keybinding.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
| command | description |
|---------+-------------------------------------------|
| ~=irc~ | Connect to IRC and all configured servers |
To connect to IRC use ~M-x =irc~.
When in a circe buffer these keybindings will be available.
When in a circe buffer these keybindings will be available:
| command | key | description |
|-----------------------------+-----------------+----------------------------------------------|
| ~+irc/tracking-next-buffer~ | [[kbd:][<localleader> a]] | Switch to the next active buffer |
| ~circe-command-JOIN~ | [[kbd:][<localleader> j]] | Join a channel |
| ~+irc/send-message~ | [[kbd:][<localleader> m]] | Send a private message |
| ~circe-command-NAMES~ | [[kbd:][<localleader> n]] | List the names of the current channel |
| ~circe-command-PART~ | [[kbd:][<localleader> p]] | Part the current channel |
| ~+irc/quit~ | [[kbd:][<localleader> Q]] | Kill the current circe session and workgroup |
| ~circe-reconnect~ | [[kbd:][<localleader> R]] | Reconnect the current server |
| command | key | description |
|-----------------------------+-----------+----------------------------------------------|
| ~+irc/tracking-next-buffer~ | =SPC m a= | Switch to the next active buffer |
| ~circe-command-JOIN~ | =SPC m j= | Join a channel |
| ~+irc/send-message~ | =SPC m m= | Send a private message |
| ~circe-command-NAMES~ | =SPC m n= | List the names of the current channel |
| ~circe-command-PART~ | =SPC m p= | Part the current channel |
| ~+irc/quit~ | =SPC m Q= | Kill the current circe session and workgroup |
| ~circe-reconnect~ | =SPC m R= | Reconnect the current server |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument (a plist)
takes the same arguments as ~circe-network-options~.
#+BEGIN_SRC emacs-lisp :tangle no
Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument
(a plist) takes the same arguments as ~circe-network-options~:
#+begin_src emacs-lisp
;; if you omit =:host=, ~SERVER~ will be used instead.
(after! circe
(set-irc-server! "irc.libera.chat"
@ -86,20 +86,23 @@ takes the same arguments as ~circe-network-options~.
:sasl-username "myusername"
:sasl-password "mypassword"
:channels ("#emacs"))))
#+END_SRC
#+end_src
However, *it is a obviously a bad idea to store your password in plaintext,* so
here are ways to avoid that:
** Pass: the unix password manager
** TODO Pass: the unix password manager
#+begin_quote
🔨 /This section is outdated and needs to be rewritten./ [[doom-contrib-module:][Rewrite it?]]
#+end_quote
[[https://www.passwordstore.org/][Pass]] is my tool of choice. I use it to manage my passwords. If you activate the
[[../../../modules/tools/pass/README.org][:tools pass]] module you get an elisp API through which to access your
password store.
[[doom-module:][:tools pass]] module you get an elisp API through which to access your password
store.
~set-irc-server!~ accepts a plist can use functions instead of strings.
~+pass-get-user~ and ~+pass-get-secret~ can help here:
#+BEGIN_SRC emacs-lisp :tangle no
#+begin_src emacs-lisp
(set-irc-server! "irc.libera.chat"
`(:tls t
:port 6697
@ -107,12 +110,11 @@ password store.
:sasl-username ,(+pass-get-user "irc/libera.chat")
:sasl-password ,(+pass-get-secret "irc/libera.chat")
:channels ("#emacs")))
#+END_SRC
#+end_src
But wait, there's more! This stores your password in a public variable which
could be accessed or appear in backtraces. Not good! So we go a step further:
#+BEGIN_SRC emacs-lisp :tangle no
#+begin_src emacs-lisp
(set-irc-server! "irc.libera.chat"
`(:tls t
:port 6697
@ -120,12 +122,12 @@ could be accessed or appear in backtraces. Not good! So we go a step further:
:sasl-username ,(+pass-get-user "irc/libera.chat")
:sasl-password (lambda (&rest _) (+pass-get-secret "irc/libera.chat"))
:channels ("#emacs")))
#+END_SRC
#+end_src
And you're good to go!
Note that =+pass-get-user= tries to find your username by looking for the fields
listed in =+pass-user-fields= (by default =login=, =user==, =username== and
Note that ~+pass-get-user~ tries to find your username by looking for the fields
listed in ~+pass-user-fields~ (by default =login=, =user==, =username== and
=email=)=). An example configuration looks like
#+begin_example
@ -136,8 +138,7 @@ username: myusername
** Emacs' auth-source API
~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store
(and retrieve) encrypted passwords with it.
#+BEGIN_SRC emacs-lisp :tangle no
#+begin_src emacs-lisp
(setq auth-sources '("~/.authinfo.gpg"))
(defun my-fetch-password (&rest params)
@ -159,6 +160,15 @@ username: myusername
:nick "doom"
:sasl-password my-nickserver-password
:channels ("#emacs")))
#+END_SRC
#+end_src
* TODO Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

147
modules/app/rss/README.org
View file

@ -1,92 +1,102 @@
#+TITLE: app/rss
#+DATE: May 12, 2020
#+SINCE: v2.0.9
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :app rss
#+subtitle: An RSS reader that Google can't shut down
#+created: May 12, 2020
#+since: 2.0.9
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#without-org][Without +org]]
- [[#with-org][With +org]]
- [[#keybindings][Keybindings]]
- [[#news-filtering][News filtering]]
- [[#automatically-updating-feed-when-opening-elfeed][Automatically updating feed when opening elfeed]]
- [[#troubleshooting][Troubleshooting]]
* Description
+ Read RSS feeds in the comfort of DOOM (Emacs)
* Description :unfold:
Read RSS feeds in the comfort of Emacs.
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+org= to enable ~elfeed-org~ to use ~org-directory/elfeed.org~
** Module flags
- +org ::
Enable [[doom-package:][elfeed-org]], so you can configure your feeds with an org file
(={org-directory}/elfeed.org=) rather than Elisp.
** Plugins
+ [[https://github.com/skeeto/elfeed][elfeed]]
+ [[https://github.com/algernon/elfeed-goodies][elfeed-goodies]]
+ =+org=
+ [[https://github.com/remyhonig/elfeed-org][elfeed-org]]
** Packages
- [[doom-package:][elfeed]]
- [[doom-package:][elfeed-goodies]]
- [[doom-package:][elfeed-org]] if [[doom-module:][+org]]
** Hacks
+ By default ~elfeed-search-filter~ is set to ~@2-weeks-ago~ and makes the last 2 weeks of entries visible. This needs to be set after elfeed has loaded like so in your ~config.el~
#+begin_src elisp
(after! elfeed
(setq elfeed-search-filter "@1-month-ago +unread"))
- By default ~elfeed-search-filter~ is set to ~@2-weeks-ago~ and makes the last
2 weeks of entries visible. This needs to be set after elfeed has loaded like
so in your =$DOOMDIR/config.el=:
#+begin_src emacs-lisp
(after! elfeed
(setq elfeed-search-filter "@1-month-ago +unread"))
#+end_src
* Prerequisites
This module has no prerequisites.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Features
+ As there isn't currently binding for ~elfeed-update~ you can run it with ~M-x elfeed-update~
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
- As there isn't currently binding for ~elfeed-update~ you can run it with ~M-x
elfeed-update~
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Without +org
When you don't want to use org mode to manage your elfeed feeds you can put your subscriptions to personal ~config.el~ file, ex:
#+BEGIN_SRC elisp
When you don't want to use org mode to manage your elfeed feeds you can put your
subscriptions in =$DOOMDIR/config.el=:
#+begin_src emacs-lisp
(setq elfeed-feeds
'("https://this-week-in-rust.org/rss.xml"
"http://feeds.bbci.co.uk/news/rss.xml"))
#+END_SRC
#+end_src
** With +org
When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to configure feeds to follow.
#+BEGIN_SRC org
When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to
configure feeds to follow:
#+begin_src org
,* root :elfeed:
,** Programming :programming:
,*** [[https://this-week-in-rust.org/rss.xml][This Week in Rust]] :rust:
,** News :news:
,*** Top news :tops:
,**** http://feeds.bbci.co.uk/news/rss.xml
#+END_SRC
+ Root of ~elfeed-org~ needs to have ~:elfeed:~ tag. This is where ~elfeed-org~ starts to read.
+ You can have subheaders as in example ~:programming:~, and ~elfeed-org~ applies that tag to all subheader feeds, in example it adds it to ~This Week in Rust~.
+ You can "name" feeds as you please with ~org-mode~ ~org-insert-link~ (~C-c C-l~) and put name as you want into ~description~.
+ If you don't want to use ~org-directory/elfeed.org~ file you can specify it with ~(setq rmh-elfeed-org-files '("path/to/your/elfeed/file.org))~
#+end_src
- Root of ~elfeed-org~ needs to have ~:elfeed:~ tag. This is where ~elfeed-org~
starts to read.
- You can have subheaders as in example ~:programming:~, and ~elfeed-org~
applies that tag to all subheader feeds, in example it adds it to ~This Week
in Rust~.
- You can "name" feeds as you please with ~org-mode~ ~org-insert-link~ ([[kbd:][C-c C-l]])
and put name as you want into ~description~.
- If you don't want to use ~org-directory/elfeed.org~ file you can specify it
with ~(setq rmh-elfeed-org-files '("path/to/your/elfeed/file.org))~
** Keybindings
+ General
| Key | Mode | Description |
|---------+--------------------+--------------------------------|
| =S-RET= | Elfeed-search-mode | Open link into browser |
| =RET= | Elfeed-search-mode | Open item |
| =s= | Elfeed-search-mode | Filter |
| =C-j= | Elfeed-show-mode | Move to next item |
| =C-k= | Elfeed-show-mode | Move to previous item |
| Key | Mode | Description |
|-------+--------------------+------------------------|
| [[kbd:][S-RET]] | elfeed-search-mode | Open link into browser |
| [[kbd:][RET]] | elfeed-search-mode | Open item |
| [[kbd:][s]] | elfeed-search-mode | Filter |
| [[kbd:][C-j]] | elfeed-show-mode | Move to next item |
| [[kbd:][C-k]] | elfeed-show-mode | Move to previous item |
+ If ~:editor evil +everywhere~
| Key | Description |
|-----+-----------------------------|
| q | elfeed-kill-buffer |
| r | elfeed-search-update--force |
| g c | Copy link of current entry |
| [[kbd:][q]] | elfeed-kill-buffer |
| [[kbd:][r]] | elfeed-search-update--force |
| [[kbd:][g c]] | Copy link of current entry |
** News filtering
+ Time filtering
@ -106,9 +116,18 @@ When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to c
+ Exclude ~!something~
** Automatically updating feed when opening elfeed
Hook ~elfeed-update~ to ~elfeed-search-mode-hook~
#+BEGIN_SRC elisp
(add-hook! 'elfeed-search-mode-hook 'elfeed-update)
#+END_SRC
Hook ~elfeed-update~ to ~elfeed-search-mode-hook~:
#+begin_src emacs-lisp
(add-hook 'elfeed-search-mode-hook #'elfeed-update)
#+end_src
* TODO Troubleshooting
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

158
modules/app/twitter/README.org
View file

@ -1,96 +1,102 @@
#+TITLE: app/twitter
#+DATE: October 11, 2019
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :app twitter
#+subtitle: Be superficial in plain text
#+created: October 11, 2019
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
- [[#appendix][Appendix]]
- [[#commands--keybindings][Commands & Keybindings]]
* Description
* Description :unfold:
Enjoy twitter from emacs.
+ View various timelines side by side, e.g. user's timeline, home, etc.
+ Post new tweets
+ Send direct messages
+ Retweet
+ Follow and un-follow users
+ Favorite tweets
- View various timelines side by side, e.g. user's timeline, home, etc.
- Post new tweets
- Send direct messages
- Retweet
- Follow and un-follow users
- Favorite tweets
** Module Flags
This module provides no flags.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/hayamiz/twittering-mode][twittering-mode]]
+ [[https://github.com/abo-abo/avy][avy]]
** Module flags
/This module has no flags./
** TODO Hacks
{A list of internal modifications to included packages}
** Packages
- [[doom-package:][avy]]
- [[doom-package:][twittering-mode]]
* Prerequisites
** Hacks
/No hacks documented for this module./
+ For SSL connection (required by Twitter's API), one of the followings is required:
+ [[http://curl.haxx.se/][cURL]]
+ [[http://www.gnu.org/software/wget/][GNU Wget]]
+ [[http://www.openssl.org/][OpenSSL]]
+ [[http://www.gnu.org/software/gnutls/][GnuTLS]]
+ [[http://www.gnupg.org/][GnuPG]] is required for keeping the OAuth token encrypted in local storage.
+ ~twittering-icon-mode~ converts retrieved icons into XPM by default. To
achieve this and for displaying icons in formats that are not supported by
Emacs as well as for resizing icon images, [[http://www.imagemagick.org/][ImageMagick]] is required.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
To build emacs with ImageMagick support the ~--with-imagemagick~ flag needs to
be passed to the ~configure~ script, e.g. ~./configure --with-imagemagick~.
For detailed instruction on how to build Emacs from source please refer to
[[https://git.savannah.gnu.org/cgit/emacs.git/tree/INSTALL][INSTALL]] in Emacs' savannah repository.
+ For keeping retrieved icons in local storage, [[http://www.gzip.org/][gzip]] is required.
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* TODO Features
An in-depth list of features, how to use them, and their dependencies.
This module requires:
- One of the following (for SSL connections; required by Twitter's API):
- [[http://curl.haxx.se/][cURL]]
- [[http://www.gnu.org/software/wget/][GNU Wget]]
- [[http://www.openssl.org/][OpenSSL]]
- [[http://www.gnu.org/software/gnutls/][GnuTLS]]
- [[http://www.gnupg.org/][GnuPG]], for encrypting the OAuth token, stored locally.
- [[http://www.gzip.org/][gzip]], for compressing retrieved profile pictures,
- [[http://www.imagemagick.org/][ImageMagick]], for displaying and resizing profile pictures.
Build Emacs with ImageMagick support using the ~--with-imagemagick~ flag ([[https://git.savannah.gnu.org/cgit/emacs.git/tree/INSTALL][how
to build Emacs from source]]).
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Troubleshooting
Currently ~twittering-mode~ binds =SPC=, breaking its functionality as a leader
key. To work around this issue you may use =M-SPC= instead when in
~twittering-mode~.
* Appendix
** Commands & Keybindings
Here is a list of available commands and their default keybindings (defined in
[[./config.el][config.el]]).
[[./config.el][config.el]]):
| command | key / ex command | description |
|---------------------+------------------+-------------------------------------------------------------|
| ~+twitter/quit~ | =q= | Close current window |
| ~+twitter/quit-all~ | =Q= | Close all twitter windows and buffers, and delete workspace |
And when ~:editor evil +everywhere~ is active:
| ~+twitter/quit~ | [[kbd:][q]] | Close current window |
| ~+twitter/quit-all~ | [[kbd:][Q]] | Close all twitter windows and buffers, and delete workspace |
And when [[doom-module:][:editor evil +everywhere]] is active:
| command | key / ex command | description |
|--------------------------------------------------+------------------+------------------------------------------------------------------|
| ~twittering-favorite~ | =f= | Favorite/Like a tweet |
| ~twittering-unfavorite~ | =F= | Un-favorite/Un-like a tweet |
| ~twittering-follow~ | =C-f= | Follow user |
| ~twittering-unfollow~ | =C-F= | Un-follow user |
| ~twittering-delete-status~ | =d= | Delete a tweet |
| ~twittering-retweet~ | =r= | Retweet |
| ~twittering-toggle-or-retrieve-replied-statuses~ | =R= | Toggle or retrieve replies |
| ~twittering-update-status-interactive~ | =o= | Update tweets |
| ~+twitter/ace-link~ | =O= | Open some visible link from a ~twittering-mode~ buffer using ace |
| ~twittering-search~ | =/= | Search |
| ~twittering-goto-next-status~ | =J= | Go to next tweet |
| ~twittering-goto-previous-status~ | =K= | Go to previous tweet |
| ~twittering-goto-first-status~ | =gg= | Go to first tweet |
| ~twittering-goto-last-status~ | =G= | Go to last tweet |
| ~twittering-goto-next-status-of-user~ | =gj= | Go to next tweet of user |
| ~twittering-goto-previous-status-of-user)))~ | =gk= | Go to previous tweet of user |
| ~twittering-favorite~ | [[kbd:][f]] | Favorite/Like a tweet |
| ~twittering-unfavorite~ | [[kbd:][F]] | Un-favorite/Un-like a tweet |
| ~twittering-follow~ | [[kbd:][C-f]] | Follow user |
| ~twittering-unfollow~ | [[kbd:][C-F]] | Un-follow user |
| ~twittering-delete-status~ | [[kbd:][d]] | Delete a tweet |
| ~twittering-retweet~ | [[kbd:][r]] | Retweet |
| ~twittering-toggle-or-retrieve-replied-statuses~ | [[kbd:][R]] | Toggle or retrieve replies |
| ~twittering-update-status-interactive~ | [[kbd:][o]] | Update tweets |
| ~+twitter/ace-link~ | [[kbd:][O]] | Open some visible link from a ~twittering-mode~ buffer using ace |
| ~twittering-search~ | [[kbd:][/]] | Search |
| ~twittering-goto-next-status~ | [[kbd:][J]] | Go to next tweet |
| ~twittering-goto-previous-status~ | [[kbd:][K]] | Go to previous tweet |
| ~twittering-goto-first-status~ | [[kbd:][gg]] | Go to first tweet |
| ~twittering-goto-last-status~ | [[kbd:][G]] | Go to last tweet |
| ~twittering-goto-next-status-of-user~ | [[kbd:][gj]] | Go to next tweet of user |
| ~twittering-goto-previous-status-of-user)))~ | [[kbd:][gk]] | Go to previous tweet of user |
* Troubleshooting
[[doom-report:][Report an issue?]]
** ~twittering-mode~ overrides the [[kbd:][SPC]] key
Currently ~twittering-mode~ binds [[kbd:][SPC]], breaking its functionality as a leader
key for evil users. To work around this issue you may use [[kbd:][M-SPC]] instead.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

10
modules/checkers/README.org Normal file
View file

@ -0,0 +1,10 @@
# -*- mode: doom-docs-org -*-
#+title: :checkers
#+created: August 01, 2021
#+since: 21.12.0
* Description
For modules dedicated to linting plain text (primarily code and prose).
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

92
modules/checkers/grammar/README.org
View file

@ -1,68 +1,76 @@
#+TITLE: checkers/grammar
#+DATE: January 9, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :checkers grammar
#+subtitle: Tasing grammar mistake every you make
#+created: January 09, 2020
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#language-tool][Language Tool]]
- [[#commands][Commands]]
- [[#writegood-mode][writegood-mode]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds grammar checking to Emacs to aid your writing by combining
=lang-tool= and =writegood-mode=.
[[doom-package:][lang-tool]] and [[doom-package:][writegood-mode]].
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
+ [[https://github.com/mhayashi1120/Emacs-langtool][langtool]]
+ [[https://github.com/bnbeckwith/writegood-mode][writegood-mode]]
** Packages
- [[doom-package:][langtool]]
- [[doom-package:][writegood-mode]]
* Prerequisites
This module requires langtool (which requires =Java 1.8+=).
** Hacks
/No hacks documented for this module./
It can be acquired either from https://languagetool.org/ or your OS's package
manager:
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
+ macOS: ~brew install languagetool~
+ Arch Linux: ~pacman -S languagetool~
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module tries to guess the location of languagetool-commandline.jar. If you
get a warning that Doom =couldn't find languagetool-commandline.jar=, you will
need to set ~langtool-language-tool-jar~ to its location.
This module requires [[https://languagetool.org/][LanguageTool]] (which requires =Java 1.8+=).
* Features
An in-depth list of features, how to use them, and their dependencies.
It is available from either https://languagetool.org/ or your OS's package
manager. E.g.
- macOS: ~$ brew install languagetool~
- Arch Linux: ~$ pacman -S languagetool~
This module tries to guess the location of =languagetool-commandline.jar=. If
you get a warning that Doom ~couldn't find languagetool-commandline.jar~, you
will need to set ~langtool-language-tool-jar~ to its location.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Language Tool
[[https://www.languagetool.org/][Language Tool]] is a polyglot proofreader service that checks for grammar and
stylistic issues in your writing. This requires Java 1.8+.
#+begin_quote
This requires Java 1.8+
🚧 This requires Java 1.8+
#+end_quote
*** Commands
- ~langtool-check~
- ~langtool-correct-buffer~
- ~M-x langtool-check~
- ~M-x langtool-correct-buffer~
** writegood-mode
This minor mode highlights weasel words, duplication and passive voice.
* Configuration
How to configure this module, including common problems and how to address them.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
Common issues and their solution, or places to look for help.
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

241
modules/checkers/spell/README.org
View file

@ -1,149 +1,154 @@
#+TITLE: checkers/spell
#+DATE: February 20, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :checkers spell
#+subtitle: Tasing you for misspelling mispelling
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#aspell][Aspell]]
- [[#hunspell][Hunspell]]
- [[#enchant][Enchant]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#changing-how-quickly-spell-fu-spellchecks-after-changes][Changing how quickly spell-fu spellchecks after changes]]
- [[#spell-fu-users][Spell-fu users]]
- [[#flyspell-users][Flyspell users]]
- [[#reducing-false-positives-by-disabling-spelling-on-certain-faces][Reducing false positives by disabling spelling on certain faces]]
- [[#spell-fu-users-1][Spell-fu users]]
- [[#flyspell-users-1][Flyspell users]]
- [[#adding-or-removing-words-to-your-personal-dictionary][Adding or removing words to your personal dictionary]]
- [[#troubleshooting][Troubleshooting]]
* Description
This modules provides spellchecking powered by =aspell=, =hunspell= or =enchant=.
* Description :unfold:
This modules provides spellchecking powered by =aspell=, =hunspell= or
=enchant=.
Spellcheck is automatically loaded in many ~text-mode~ derivatives, which
includes ~org-mode~, ~markdown-mode~, the Git Commit buffer (from magit),
~mu4e-compose-mode~, and others.
- Spell checking and correction using =aspell=, =hunspell= or =enchant=.
- Ignores source code inside org or markdown files.
- Lazily spellchecking recent changes only when idle.
- Choosing suggestions using completion interfaces ([[doom-package:][ivy]] or [[doom-package:][helm]]).
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+flyspell= Use =flyspell= instead of =spell-fu=. It's significantly slower,
but supports multiple languages and dictionaries.
+ =+aspell= Use =aspell= as a backend for correcting words.
+ =+hunspell= Use =hunspell= as a backend for correcting words.
+ =+enchant= Use =enchant-2= as a backend for correcting words.
+ =+everywhere= Spell check in programming modes as well (in comments).
** Module flags
- +aspell ::
Use =aspell= as a backend for correcting words.
- +enchant ::
Use =enchant-2= as a backend for correcting words.
- +everywhere ::
Spell check in programming modes as well (in comments only).
- +flyspell ::
Use [[doom-package:][flyspell]] instead of [[doom-package:][spell-fu]]. It's significantly slower, but supports
multiple languages and dictionaries.
- +hunspell ::
Use =hunspell= as a backend for correcting words.
** Plugins
+ if =+flyspell=
+ [[https://github.com/d12frosted/flyspell-correct][flyspell-correct]]
+ [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-ivy-interface][flyspell-correct-ivy]] (=completion/ivy=)
+ [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-helm-interface][flyspell-correct-helm]] (=completion/helm=)
+ [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-popup-interface][flyspell-correct-popup]] (if *neither* =completion/ivy=, =completion/helm= or =completion/vertico=)
+ [[https://github.com/rolandwalker/flyspell-lazy][flyspell-lazy]]
+ else
+ [[https://gitlab.com/ideasman42/emacs-spell-fu][spell-fu]]
** Packages
- if [[doom-module:][+flyspell]]
- [[doom-package:][flyspell-correct]]
- [[doom-package:][flyspell-correct-ivy]] if [[doom-module:][:completion ivy]]
- [[doom-package:][flyspell-correct-helm]] if [[doom-module:][:completion helm]]
- [[doom-package:][flyspell-correct-popup]] unless [[doom-module:][:completion ivy]], [[doom-module:][:completion helm]], or
[[doom-module:][:completion vertico]]
- [[doom-package:][flyspell-lazy]]
- else
- [[doom-package:][spell-fu]]
* Prerequisites
This module requires one of =aspell=, =hunspell= or =enchant-2=
installed on your system and in your ~PATH~.
They also need dictionaries for your language(s).
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires one of =aspell=, =hunspell= or =enchant-2= installed on
your system and in your =$PATH=. They also need dictionaries for your
language(s).
#+begin_quote
If you *are not* using =+flyspell=, you will need aspell (and a dictionary)
installed whether or not you have =+hunspell= or =+enchant= enabled.
This is because =spell-fu= does not support generating the word list
with anything other than =aspell= yet.
🚧 If you *are not* using [[doom-module:][+flyspell]], you will need =aspell= (and a dictionary)
installed whether or not you have [[doom-module:][+hunspell]] or [[doom-module:][+enchant]] enabled. This is
because [[doom-package:][spell-fu]] does not support generating the word list with anything
other than =aspell= yet.
#+end_quote
** Aspell
+ Ubuntu: ~apt-get install aspell aspell-en~
+ macOS: ~brew install aspell~
+ Arch Linux: ~pacman -S aspell aspell-en~
+ NixOS:
#+BEGIN_SRC nix
- Ubuntu: ~$ apt-get install aspell aspell-en~
- macOS: ~$ brew install aspell~
- Arch Linux: ~$ pacman -S aspell aspell-en~
- NixOS:
#+begin_src nix
{
environment.systemPackages = with pkgs; [
(aspellWithDicts (dicts: with dicts; [ en en-computers en-science ]))
];
}
#+END_SRC
#+end_src
** Hunspell
+ Ubuntu: ~apt-get install hunspell~
+ macOS: ~brew install hunspell~
+ Arch Linux: ~pacman -S hunspell~
+ NixOS:
#+BEGIN_SRC nix
- Ubuntu: ~$ apt-get install hunspell~
- macOS: ~$ brew install hunspell~
- Arch Linux: ~$ pacman -S hunspell~
- NixOS:
#+begin_src nix
{
environment.systemPackages = with pkgs; [
hunspell
];
}
#+END_SRC
#+end_src
** Enchant
+ Ubuntu: ~apt-get install enchant-2~
+ macOS: ~brew install enchant~
+ Arch Linux: ~pacman -S enchant~
+ NixOS:
#+BEGIN_SRC nix
- Ubuntu: ~$ apt-get install enchant-2~
- macOS: ~$ brew install enchant~
- Arch Linux: ~$ pacman -S enchant~
- NixOS:
#+begin_src nix
{
environment.systemPackages = with pkgs; [
enchant
];
}
#+END_SRC
#+end_src
Enchant is just a wrapper for other spelling libraries
and you will need to have at least one of the supported backends installed as well.
Enchant is just a wrapper for other spelling libraries and you will need to
have at least one of the supported backends installed as well.
* Features
+ Spell checking and correction using =aspell=, =hunspell= or =enchant=.
+ Ignores source code inside org or markdown files.
+ Lazily spellchecking recent changes only when idle.
+ Choosing suggestions using completion interfaces (=ivy= or =helm=).
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
When using =+everywhere=, spell checking is performed for as many major modes as
When using [[doom-module:][+everywhere]], spell checking is performed for as many major modes as
possible, and not only ~text-mode~ derivatives. e.g. in comments for programming
major modes.
* Configuration
Dictionary is set by =ispell-dictionary= variable. Can be changed locally with
the function =ispell-change-dictionary=.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Changing how quickly spell-fu spellchecks after changes
Dictionary is set by ~ispell-dictionary~ variable. Can be changed locally with
the function ~ispell-change-dictionary~.
** Changing how quickly spelling is checked after changes
*** Spell-fu users
Adjust ~spell-fu-idle-delay~ to change how long Emacs waits to spellcheck after
recent changes.
#+BEGIN_SRC elisp
recent changes:
#+begin_src emacs-lisp
(after! spell-fu
(setq spell-fu-idle-delay 0.5)) ; default is 0.25
#+END_SRC
#+end_src
*** Flyspell users
Lazy spellcheck is provided by =flyspell-lazy= package.
Lazy spellcheck is provided by [[doom-package:][flyspell-lazy]] package.
=flyspell-lazy-idle-seconds= sets how many idle seconds until spellchecking
recent changes (default as 1), while =flyspell-lazy-window-idle-seconds= sets
how many seconds until the whole window is spellchecked (default as 3).
#+BEGIN_SRC elisp
~flyspell-lazy-idle-seconds~ sets how many idle seconds until spellchecking
recent changes (default as 1), while ~flyspell-lazy-window-idle-seconds~ sets
how many seconds until the whole window is spellchecked (default as 3):
#+begin_src emacs-lisp
(after! flyspell
(setq flyspell-lazy-idle-seconds 2))
#+END_SRC
#+end_src
** Reducing false positives by disabling spelling on certain faces
*** Spell-fu users
Users can exclude what faces to preform spellchecking on by adjusting
~+spell-excluded-faces-alist~ in a buffer-local hook:
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(setf (alist-get 'markdown-mode +spell-excluded-faces-alist)
'(markdown-code-face
markdown-reference-face
@ -153,18 +158,19 @@ Users can exclude what faces to preform spellchecking on by adjusting
markdown-html-attr-value-face
markdown-html-attr-name-face
markdown-html-tag-name-face))
#+END_SRC
#+end_src
*** Flyspell users
Flyspell will run a series of predicate functions to determine if a word should be spell checked. You can add your own with ~set-flyspell-predicate!~:
#+BEGIN_SRC elisp
Flyspell will run a series of predicate functions to determine if a word should
be spell checked. You can add your own with ~set-flyspell-predicate!~:
#+begin_src emacs-lisp
(set-flyspell-predicate! '(markdown-mode gfm-mode)
#'+markdown-flyspell-word-p)
#+END_SRC
#+end_src
Flyspell predicates take no arguments and must return a boolean to determine if
the word at point should be spell checked. For example:
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(defun +markdown-flyspell-word-p ()
"Return t if point is on a word that should be spell checked.
@ -183,13 +189,46 @@ Return nil if on a link url, markup, html, or references."
for face in faces
if (memq face unsafe-faces)
return t)))))
#+END_SRC
#+end_src
** Adding or removing words to your personal dictionary
Use ~M-x +spell/add-word~ and ~M-x +spell/remove-word~ to whitelist words that
you know are not misspellings. For evil users these are bound to =zg= and =zw=,
respectively. =+flyspell= users can also add/remove words from the
~flyspell-correct~ popup interface (there will be extra options on the list of
you know are not misspellings. For evil users these are bound to [[kbd:][zg]] and [[kbd:][zw]],
respectively. [[doom-module:][+flyspell]] users can also add/remove words from the
[[doom-package:][flyspell-correct]] popup interface (there will be extra options on the list of
corrections for "save word to dictionary").
* TODO Troubleshooting
* Troubleshooting
[[doom-report:][Report an issue?]]
** spell-fu highlights every single word
[[doom-package:][spell-fu]] caches its word list. If it was activated before your dictionaries were
installed, it will generate an empty word list, causing it to highlight all
words as incorrect. Delete its cache files in =$EMACSDIR/.local/etc/spell-fu/=
to fix this.
** Cannot add [word] to any active dictionary
*** Aspell
If ~M-x +spell/add-word~ results in the above error this mean that the
personal dictionary file was not created for some reason. This can be
fixed by creating the required file manually.
#+begin_example shell
mkdir -p ~/.emacs.d/.local/etc/ispell
echo personal_ws-1.1 en 0 > ~/.emacs.d/.local/etc/ispell/.pws
#+end_example
Where ~personal_ws-1.1 en 0~ is the required header format for the personal
dictionary file. ~en~ is the language you're writing in and have a dict
installed and ~0~ is the number of added words in the dictionary. If you are
planning of updating the file with the list of words, update the number
accordingly.
After the file is created, restart emacs and adding words should work.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

118
modules/checkers/syntax/README.org
View file

@ -1,66 +1,84 @@
#+TITLE: checkers/syntax
#+DATE: February 20, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :checkers syntax
#+subtitle: Tasing you for every semicolon you forget
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
This module provides syntax checking and error highlighting, powered by [[https://github.com/flycheck/flycheck][flycheck]]
+ If possible, include a brief list of feature highlights here
+ Like code completion, syntax checking or available snippets
+ Include links to packages & external things where possible
* Description :unfold:
This module provides syntax checking and error highlighting, powered by
[[doom-package:][flycheck]].
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+childframe= Enables displaying completion candidates in a child frame, rather than an overlay or tooltip (among with other UI enhancements).
** Module flags
- +childframe ::
Display errors/warnings in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or tooltip.
*Requires GUI Emacs.*
** Plugins
+ [[https://github.com/flycheck/flycheck][flycheck]]
+ [[https://github.com/flycheck/flycheck-popup-tip][flycheck-popup-tip]]
+ =+childframe=
+ [[https://github.com/alexmurray/flycheck-posframe][flycheck-posframe]]
** Packages
- [[doom-package:][flycheck]]
- [[doom-package:][flycheck-popup-tip]]
- [[doom-package:][flycheck-posframe]] if [[doom-module:][+childframe]]
** Hacks
If =lsp-ui-mode= is active, most of the aesthetic functionality of this module is turned off, as they show the same information.
- If ~lsp-ui-mode~ is active, most of the aesthetic functionality of this module
is turned off, as they show the same information.
* Prerequisites
This module has no direct prerequisites.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
However, some major modes may require a specific linter or program to work, and some major modes may not work at all. The best way to find these dependencies is by either reading the documentation for that module, or running =doom doctor=.
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module has no direct requirements, but some languages may have their own
requirements to fulfill before you get syntax checking in them (and some
languages may lack syntax checking support altogether). Run ~$ doom doctor~ to
find out if you're missing any dependencies.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Most of flycheck's features are under [[kbd:][C-c !]], regardless of whether evil mode is
used.
* Features
Most of flycheck's features are under =C-c !=, regardless of whether evil mode is used.
| Keybind | Description |
| C-c ! ? | Describe Checker ] |
| C-c ! c | Check syntax in buffer |
| C-c ! l | List errors |
| C-c ! n | Next Error |
| C-c ! p | Previous error |
| C-c ! C | Clear all errors in buffer |
| C-c ! e | Explain error at point |
| C-c ! h | Display all errors at point |
|---------+-----------------------------|
| [[kbd:][C-c ! ?]] | Describe Checker |
| [[kbd:][C-c ! c]] | Check syntax in buffer |
| [[kbd:][C-c ! l]] | List errors |
| [[kbd:][C-c ! n]] | Next Error |
| [[kbd:][C-c ! p]] | Previous error |
| [[kbd:][C-c ! C]] | Clear all errors in buffer |
| [[kbd:][C-c ! e]] | Explain error at point |
| [[kbd:][C-c ! h]] | Display all errors at point |
Evil Specific
Evil Specific:
| Keybind | Description |
| SPC t f | Toggle Flycheck |
| SPC c x | List errors |
| ] e | Next error |
| [ e | Prevous error |
|---------+-----------------|
| [[kbd:][SPC t f]] | Toggle Flycheck |
| [[kbd:][SPC c x]] | List errors |
| [[kbd:][] e]] | Next error |
| [[kbd:][[ e]] | Prevous error |
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
* Troubleshooting
[[doom-report:][Report an issue?]]
- Use ~M-x flycheck-verify-setup~ to determine what checkers are available in a
buffer and whether they're active or not (and why).
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

19
modules/completion/README.org Normal file
View file

@ -0,0 +1,19 @@
# -*- mode: doom-docs-org -*-
#+title: :completion
#+created: July 29, 2021
#+since: 21.12.0
* Description
These modules provide interfaces and frameworks completion, including code
completion.
* Frequently asked questions
** Should I choose Ivy, Helm, Vertico, or Ido?
:PROPERTIES:
:ID: 4f36ae11-1da8-4624-9c30-46b764e849fc
:END:
Vertico is Doom's default and comes highly recommended of the four. It is the
fastest, best integrated in Doom's ecosystem, and its module is the most
actively maintained of the four. It also has the cleanest codebase and ties into
native functionality already existing in Emacs, rather than reinventing the
wheel.

169
modules/completion/company/README.org
View file

@ -1,92 +1,103 @@
#+TITLE: completion/company
#+DATE: February 19, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :completion company
#+subtitle: The ultimate code completion backend
#+created: February 19, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#code-completion][Code completion]]
- [[#vim-esque-omni-completion-prefix-c-x][Vim-esque omni-completion prefix (C-x)]]
- [[#configuration][Configuration]]
- [[#enable-company-backends-in-certain-modes][Enable company backend(s) in certain modes]]
- [[#troubleshooting][Troubleshooting]]
- [[#x-mode-doesnt-have-code-completion-support-or-requires-extra-setup][X-mode doesn't have code completion support or requires extra setup.]]
- [[#no-backends-or-the-incorrect-ones-have-been-registered-for-x-mode][No backends (or the incorrect ones) have been registered for X-mode.]]
* Description
This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. It is required
for code completion in many of Doom's :lang modules.
* Description :unfold:
This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. Many of Doom's
[[doom-module:][:lang]] modules require it for "intellisense" functionality.
https://assets.doomemacs.org/completion/company/overlay.png
** Module Flags
+ =+childframe= Enables displaying completion candidates in a child frame,
rather than an overlay or tooltip (among with other UI enhancements). *This
requires GUI Emacs 26.1+ and is incompatible with the =+tng= flag*
+ =+tng= Enables completion using only ~TAB~. Pressing ~TAB~ will select the
next completion suggestion, while ~S-TAB~ will select the previous one. *This
is incompatible with the =+childframe= flag*
** Maintainers
- [[doom-user:][@hlissner]]
** Plugins
+ [[https://github.com/company-mode/company-mode][company-mode]]
+ [[https://github.com/hlissner/emacs-company-dict][company-dict]]
+ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=)
[[doom-contrib-maintainer:][Become a maintainer?]]
* Prerequisites
This module has no direct prerequisites.
** Module flags
- +childframe ::
Display completion candidates in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or
tooltip. *Requires GUI Emacs.*
- +tng ::
Invoke completion on [[kbd:][TAB]] instad of [[kbd:][C-SPC]]. When company is active, [[kbd:][TAB]] and
[[kbd:][S-TAB]] will navigate the completion candidates.
However, some major modes may require additional setup for code completion to
work in them. Some major modes may have no completion support at all. Check that
major mode's module's documentation for details.
** Packages
- [[doom-package:][company-box]] if [[doom-module:][+childframe]]
- [[doom-package:][company-dict]]
- [[doom-package:][company-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module has no direct requirements, but some languages may have their own
requirements to fulfill before you get code completion in them (and some
languages may lack code completion support altogether). Run ~$ doom doctor~ to
find out if you're missing any dependencies.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
** Code completion
By default, completion is triggered after a short idle period or with the
=C-SPC= key. While the popup is visible, the following keys are available:
[[kbd:][C-SPC]] key. While the popup is visible, the following keys are available:
| Keybind | Description |
|---------+------------------------------------------|
| =C-n= | Go to next candidate |
| =C-p= | Go to previous candidate |
| =C-j= | (evil) Go to next candidate |
| =C-k= | (evil) Go to previous candidate |
| =C-h= | Display documentation (if available) |
| =C-u= | Move to previous page of candidates |
| =C-d= | Move to next page of candidates |
| =C-s= | Filter candidates |
| =C-S-s= | Search candidates with helm/ivy |
| =C-SPC= | Complete common |
| =TAB= | Complete common or select next candidate |
| =S-TAB= | Select previous candidate |
| [[kbd:][C-n]] | Go to next candidate |
| [[kbd:][C-p]] | Go to previous candidate |
| [[kbd:][C-j]] | (evil) Go to next candidate |
| [[kbd:][C-k]] | (evil) Go to previous candidate |
| [[kbd:][C-h]] | Display documentation (if available) |
| [[kbd:][C-u]] | Move to previous page of candidates |
| [[kbd:][C-d]] | Move to next page of candidates |
| [[kbd:][C-s]] | Filter candidates |
| [[kbd:][C-S-s]] | Search candidates with helm/ivy |
| [[kbd:][C-SPC]] | Complete common |
| [[kbd:][TAB]] | Complete common or select next candidate |
| [[kbd:][S-TAB]] | Select previous candidate |
** Vim-esque omni-completion prefix (C-x)
In the spirit of Vim's omni-completion, the following insert mode keybinds are
available to evil users to access specific company backends:
| Keybind | Description |
|---------+-----------------------------------|
| [[kbd:][C-x C-]]​] | Complete etags |
| [[kbd:][C-x C-f]] | Complete file path |
| [[kbd:][C-x C-k]] | Complete from dictionary/keyword |
| [[kbd:][C-x C-l]] | Complete full line |
| [[kbd:][C-x C-o]] | Invoke complete-at-point function |
| [[kbd:][C-x C-n]] | Complete next symbol at point |
| [[kbd:][C-x C-p]] | Complete previous symbol at point |
| [[kbd:][C-x C-s]] | Complete snippet |
| [[kbd:][C-x s]] | Complete spelling suggestions |
| Keybind | Description |
|-----------+-----------------------------------|
| =C-x C-]= | Complete etags |
| =C-x C-f= | Complete file path |
| =C-x C-k= | Complete from dictionary/keyword |
| =C-x C-l= | Complete full line |
| =C-x C-o= | Invoke complete-at-point function |
| =C-x C-n= | Complete next symbol at point |
| =C-x C-p= | Complete previous symbol at point |
| =C-x C-s= | Complete snippet |
| =C-x s= | Complete spelling suggestions |
** Searching with multiple keywords
If the =vertico= module is enabled, users can perform code completion with multiple search keywords with an ampersand =&=.
More information can be found [[https://github.com/oantolin/orderless#company][here]].
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Enable company backend(s) in certain modes
The ~set-company-backend!~ function exists for setting ~company-backends~
buffer-locally in MODES, which is either a major-mode symbol, a minor-mode
symbol, or a list of either. BACKENDS are prepended to ~company-backends~ for
those modes.
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(after! js2-mode
(set-company-backend! 'js2-mode 'company-tide 'company-yasnippet))
@ -97,20 +108,18 @@ those modes.
(after! cc-mode
(set-company-backend! 'c-mode
'(:separate company-irony-c-headers company-irony)))
#+END_SRC
#+end_src
To unset the backends for a particular mode, pass ~nil~ to it:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(after! sh-script
(set-company-backend! 'sh-mode nil))
#+END_SRC
#+end_src
* Troubleshooting
If code completion isn't working for you, consider the following common causes
before you file a bug report:
[[doom-report:][Report an issue?]]
** X-mode doesn't have code completion support or requires extra setup.
** X-mode doesn't have code completion support or requires extra setup
There is no guarantee your language mode will have completion support.
Some, like ~lua-mode~, don't have completion support in Emacs at all. Others may
@ -120,11 +129,19 @@ requires that you have a Robe server running (~M-x robe-start~).
Check the relevant module's documentation for this kind of information.
** No backends (or the incorrect ones) have been registered for X-mode.
Doom expects every mode to have an explicit list of company-backends (and as
** No backends (or the incorrect ones) have been registered for X-mode
Doom expects every mode to have an explicit list of ~company-backends~ (and as
short a list as possible). This may mean you aren't getting all the completion
you want or any at all.
Check the value of ~company-backends~ (=SPC h v company-backends=) from that
mode to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for
details on changing what backends are available for that mode.
Check the value of ~company-backends~ ([[kbd:][SPC h v company-backends]]) from that mode
to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for details
on changing what backends are available for that mode.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

228
modules/completion/helm/README.org
View file

@ -1,169 +1,183 @@
#+TITLE: completion/helm
#+DATE: January 22, 2021
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :completion helm
#+subtitle: A tank for hunting a house fly
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#jump-to-navigation][Jump-to navigation]]
- [[#project-search--replace][Project search & replace]]
- [[#search][Search]]
- [[#replace][Replace]]
- [[#in-buffer-searching][In-buffer searching]]
- [[#helm-integration-for-various-completing-commands][Helm integration for various completing commands]]
- [[#general][General]]
- [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]]
- [[#search-1][Search]]
- [[#configuration][Configuration]]
- [[#icons][Icons]]
- [[#posframe][Posframe]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module provides Helm integration for a variety of Emacs commands, as well
as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep][Ripgrep]].
* Description
This module provides Helm integration for a variety of Emacs commands, as well as
a unified interface for project search and replace, powered by ripgrep.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +childframe ::
Display Helm windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires
GUI Emacs.*
- +fuzzy ::
Enable fuzzy completion for Helm searches.
- +icons ::
Display icons on completion results (where possible) using either
[[doom-package:][all-the-icons]] or [[doom-package:][treemacs]] iconsets.
** Packages
- [[doom-package:][helm]]
- [[doom-package:][helm-company]]
- [[doom-package:][helm-c-yasnippet]]
- [[doom-package:][helm-descbinds]]
- [[doom-package:][helm-describe-modes]]
- [[doom-package:][helm-flx]]* if [[doom-module:][+fuzzy]]
- [[doom-package:][helm-icons]]* if [[doom-module:][+icons]]
- [[doom-package:][helm-org]]* if [[doom-module:][:lang org]]
- [[doom-package:][helm-posframe]]* if [[doom-module:][+childframe]]
- [[doom-package:][helm-projectile]]
- [[doom-package:][helm-rg]]
- [[doom-package:][helm-swiper]]
** TODO Hacks
#+begin_quote
I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's
lighter, simpler and faster in many cases.
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
Ivy is considered a first-class citizen in Doom, however it is still possible to use Helm if you so desire.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
** Module Flags
+ =+fuzzy= Enables fuzzy completion for Helm searches.
+ =+childframe= Causes Helm to display in a floating child frame, above Emacs.
+ =+icons= Enables icons (supports both =all-the-icons= and =treemacs= icons)
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
** Plugins
+ [[https://github.com/emacs-helm/helm][helm]]
+ [[https://github.com/microamp/helm-rg][helm-rg]]
+ [[https://github.com/emacs-jp/helm-c-yasnippet][helm-c-yasnippet]]
+ [[https://github.com/tuhdo/helm-company][helm-company]]
+ [[https://github.com/emacs-helm/helm-describe-modes][helm-describe-modes]]
+ [[https://github.com/bbatsov/helm-projectile][helm-projectile]]
+ [[https://github.com/abo-abo/swiper-helm][helm-swiper]]
+ [[https://github.com/emacs-helm/helm-descbinds][helm-descbinds]]
+ [[https://github.com/PythonNut/helm-flx][helm-flx]]* (=+fuzzy=)
+ [[https://github.com/tumashu/helm-posframe][helm-posframe]]* (=+childframe=)
+ [[https://github.com/emacs-helm/helm-org][helm-org]]* (=:lang org=)
+ [[https://github.com/yyoncho/helm-icons][helm-icons]]* (=+icons=)
This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of
Doom itself, so you should already have it installed.
* Prerequisites
This module has no prerequisites.
Otherwise, Helm provides many commands to interface with a variety of programs
from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These programs are optional
for this module, but must be installed if you intend to use their associated
Helm command or plugin.
* Features
Much like Ivy, Helm is a /large/ framework and as such
covering everything is not in scope, however a number
of Doom-specific features are shown below:
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Much like [[doom-package:][ivy]] and [[doom-package:][vertico]], [[doom-package:][helm]] is a /large/ framework. Covering all its
features is not within the scope of this module's documentation, so only its
highlights will be covered here.
** Jump-to navigation
Similar to Ivy, this module provides an interface to
navigate within a project using =projectile=:
Similar to Ivy, this module provides an interface to navigate within a project
using [[doom-package:][projectile]]:
| Keybind | Description |
|------------------+-------------------------------------|
| =SPC p f=, =SPC SPC= | Jump to file in project |
| =SPC f f=, =SPC .= | Jump to file from current directory |
| =SPC s i= | Jump to symbol in file |
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
| [[kbd:][SPC s i]] | Jump to symbol in file |
** Project search & replace
This module also provides interacetive text search and replace using ripgrep
This module also provides interactive text search and replace using ripgrep.
*** Search
| Keybind | Description |
|---------+--------------------------|
| =SPC s p= | Search project |
| =SPC s P= | Search another project |
| =SPC s d= | Search this directory |
| =SPC s D= | Search another directory |
Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u=
| [[kbd:][SPC s p]] | Search project |
| [[kbd:][SPC s P]] | Search another project |
| [[kbd:][SPC s d]] | Search this directory |
| [[kbd:][SPC s D]] | Search another directory |
Prefixing these keys with the universal argument ([[kbd:][SPC u]] for evil users; [[kbd:][C-u]]
otherwise) changes the behavior of these commands, instructing the underlying
search engine to include ignored files.
This module also provides Ex Commands for evil users:
| Ex command | Description |
|------------------------+------------------------------------------------------------------|
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
| ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) |
The optional `!` is equivalent to the universal argument for the previous
The optional ~!~ is equivalent to the universal argument for the previous
commands.
*** Replace
These keybindings are available while a search is active:
| Keybind | Description |
|---------+-----------------------------------------------|
| [[kbd:][C-c C-o]] | Open a buffer with your search results |
| [[kbd:][C-c C-e]] | Open a writable buffer of your search results |
| [[kbd:][C-SPC]] | Preview the current candidate |
| [[kbd:][C-RET]] | Open the selected candidate in other-window |
| Keybind | Description |
|-----------+-----------------------------------------------|
| =C-c C-o= | Open a buffer with your search results |
| =C-c C-e= | Open a writable buffer of your search results |
| =C-SPC= | Preview the current candidate |
| =C-RET= | Open the selected candidate in other-window |
Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed
with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil
users).
Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with
[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users).
** In-buffer searching
The =swiper= package provides an interactive buffer search powered by helm. It
can be invoked with:
The [[doom-package:][swiper]] package provides an interactive buffer search powered by helm. It can
be invoked with:
- [[kbd:][SPC s s]] (~swiper-isearch~)
- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~)
- [[kbd:][SPC s b]] (~swiper~)
- ~:sw[iper] [QUERY]~
+ =SPC s s= (~swiper-isearch~)
+ =SPC s S= (~swiper-isearch-thing-at-point~)
+ =SPC s b= (~swiper~)
+ ~:sw[iper] [QUERY]~
A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]].
A wgrep buffer can be opened from swiper with =C-c C-e=.
** Helm integration for various completing commands
Helm also has a number of overrides for built-in functionality:
*** General
| Keybind | Description |
|------------+---------------------------|
| =M-x=, =SPC := | Smarter, smex-powered M-x |
| =SPC '= | Resume last ivy session |
| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x |
| [[kbd:][SPC ']] | Resume last ivy session |
*** Jump to files, buffers or projects
| Keybind | Description |
|------------------+---------------------------------------|
| =SPC RET= | Find bookmark |
| =SPC f f=, =SPC .= | Browse from current directory |
| =SPC p f=, =SPC SPC= | Find file in project |
| =SPC f r= | Find recently opened file |
| =SPC p p= | Open another project |
| =SPC b b=, =SPC ,= | Switch to buffer in current workspace |
| =SPC b B=, =SPC <= | Switch to buffer |
| [[kbd:][SPC RET]] | Find bookmark |
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
| [[kbd:][SPC f r]] | Find recently opened file |
| [[kbd:][SPC p p]] | Open another project |
| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
*** Search
| Keybind | Description |
|---------+-------------------------------------------|
| =SPC p t= | List all TODO/FIXMEs in project |
| =SPC s b= | Search the current buffer |
| =SPC s d= | Search this directory |
| =SPC s D= | Search another directory |
| =SPC s i= | Search for symbol in current buffer |
| =SPC s p= | Search project |
| =SPC s P= | Search another project |
| =SPC s s= | Search the current buffer (incrementally) |
| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
| [[kbd:][SPC s b]] | Search the current buffer |
| [[kbd:][SPC s d]] | Search this directory |
| [[kbd:][SPC s D]] | Search another directory |
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
| [[kbd:][SPC s p]] | Search project |
| [[kbd:][SPC s P]] | Search another project |
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Icons
Icons are now included, and support 2 providers ([[https://github.com/domtronn/all-the-icons.el][all-the-icons]] and [[https://github.com/Alexander-Miller/treemacs][treemacs]]).
By default, to maintain consistency we use =all-the-icons=; however if you wish
to modify this you can do so using the below snippet:
Icon support is now included, through one of two providers: [[doom-package:][all-the-icons]] and
[[doom-package:][treemacs]]. By default, to maintain consistency we use [[doom-package:][all-the-icons]]; however if
you wish to modify this you can do so using the below snippet:
#+begin_src emacs-lisp
(after! helm
(setq helm-icons-provider 'treemacs))
#+end_src
** Posframe
** TODO Posframe
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
** Helm vs Ivy vs Ido vs Vertico
See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]].
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

57
modules/completion/ido/README.org Normal file
View file

@ -0,0 +1,57 @@
# -*- mode: doom-docs-org -*-
#+title: :completion ido
#+subtitle: A foil for other search engines
#+created: February 20, 2017
#+since: 2.0.0
* Description :unfold:
Interactive DO things. The completion engine that is /mostly/ built-into Emacs.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][crm-custom]]
- [[doom-package:][flx-ido]]
- [[doom-package:][ido-completing-read+]]
- [[doom-package:][ido-sort-mtime]]
- [[doom-package:][ido-vertical-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
** Helm vs Ivy vs Ido vs Vertico
See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]].
* Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

4
modules/completion/ido/config.el
View file

@ -9,7 +9,6 @@
(use-package! ido
:hook (doom-first-input . ido-mode)
:hook (ido-mode . ido-everywhere)
:hook (ido-mode . ido-ubiquitous-mode)
:preface
;; HACK `ido' is a really old package. It defines `ido-mode' manually and
@ -29,7 +28,8 @@
ido-confirm-unique-completion t
ido-case-fold t
ido-create-new-buffer 'always
ido-enable-flex-matching t)
ido-enable-flex-matching t
ido-everywhere t)
(map! :map (ido-common-completion-map ido-file-completion-map)
"C-w" #'ido-delete-backward-word-updir

227
modules/completion/ivy/README.org
View file

@ -1,28 +1,10 @@
#+TITLE: completion/ivy
#+DATE: February 13, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :completion ivy
#+subtitle: Yesterday's lightest search engine
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#jump-to-navigation][Jump-to navigation]]
- [[#project-search--replace][Project search & replace]]
- [[#in-buffer-searching][In-buffer searching]]
- [[#ivy-integration-for-various-completing-commands][Ivy integration for various completing commands]]
- [[#general][General]]
- [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]]
- [[#search][Search]]
- [[#configuration][Configuration]]
- [[#enable-fuzzynon-fuzzy-search-for-specific-commands][Enable fuzzy/non-fuzzy search for specific commands]]
- [[#change-the-position-of-the-ivy-childframe][Change the position of the ivy childframe]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module provides Ivy integration for a variety of Emacs commands, as well as
a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]].
@ -31,63 +13,87 @@ I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's
lighter, simpler and faster in many cases.
#+end_quote
** Module Flags
+ =+fuzzy= Enables fuzzy completion for Ivy searches.
+ =+prescient= Enables prescient filtering and sorting for Ivy searches.
+ =+childframe= Causes Ivy to display in a floating child frame, above Emacs.
+ =+icons= Enables file icons for switch-{buffer,project}/find-file counsel
commands.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/abo-abo/swiper][ivy]]
+ [[https://github.com/abo-abo/swiper][counsel]]
+ [[https://github.com/ericdanan/counsel-projectile][counsel-projectile]]
+ [[https://github.com/abo-abo/swiper][swiper]]
+ [[https://github.com/abo-abo/swiper][ivy-hydra]]
+ [[https://github.com/yevgnen/ivy-rich][ivy-rich]]
+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]]
+ [[https://github.com/DarwinAwardWinner/amx][amx]]
+ [[https://github.com/lewang/flx][flx]]* (=+fuzzy=)
+ [[https://github.com/raxod502/prescient.el][prescient]]* (=+prescient=)
+ [[https://github.com/tumashu/ivy-posframe][ivy-posframe]]* (=+childframe=)
+ [[https://github.com/asok/all-the-icons-ivy][all-the-icons-ivy]]* (=+icons=)
** Module flags
- +childframe ::
Display Ivy windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires
GUI Emacs.*
- +fuzzy ::
Enable fuzzy completion for Ivy searches.
- +icons ::
Enable file icons for switch-{buffer,project}/find-file commands.
- +prescient ::
Enable prescient filtering and sorting for Ivy searches.
** Packages
- [[doom-package:][all-the-icons-ivy]]* if [[doom-module:][+icons]]
- [[doom-package:][amx]]
- [[doom-package:][counsel]]
- [[doom-package:][counsel-projectile]]
- [[doom-package:][flx]]* if [[doom-module:][+fuzzy]]
- [[doom-package:][ivy]]
- [[doom-package:][ivy-hydra]]
- [[doom-package:][ivy-posframe]]* if [[doom-module:][+childframe]]
- [[doom-package:][ivy-rich]]
- [[doom-package:][prescient]]* if [[doom-module:][+prescient]]
- [[doom-package:][swiper]]
- [[doom-package:][wgrep]]
** Hacks
+ Functions with ivy/counsel equivalents have been globally remapped (like
- Functions with ivy/counsel equivalents have been globally remapped (like
~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will
invoke ~counsel-find-file~ instead.
+ ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex
- ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex
command)
* Prerequisites
This module has no prerequisites.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Features
Ivy and its ilk are large plugins. Covering everything about them is outside of
this documentation's scope, so only Doom-specific Ivy features are listed here:
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of
Doom itself, so you should already have it installed.
Otherwise, Counsel (an Ivy plugin) provides many commands to interface with a
variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These
programs are optional for this module, but must be installed if you intend to
use their associated Helm command or plugin.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
[[doom-package:][ivy]] is a /large/ framework for completing things. Covering all its features is
not within the scope of this module's documentation, so only its highlights will
be covered here.
** Jump-to navigation
Inspired by Sublime Text's jump-to-anywhere, CtrlP/Unite in Vim, and Textmate's
Command-T, this module provides similar functionality by bringing ~projectile~
and ~ivy~ together.
Command-T, this module provides similar functionality by bringing [[doom-package:][projectile]] and
[[doom-package:][ivy]] together.
https://assets.doomemacs.org/completion/ivy/projectile.png
| Keybind | Description |
|----------------------+-------------------------------------|
| =SPC p f=, =SPC SPC= | Jump to file in project |
| =SPC f f=, =SPC .= | Jump to file from current directory |
| =SPC s i= | Jump to symbol in file |
| Keybind | Description |
|------------------+-------------------------------------|
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
| [[kbd:][SPC s i]] | Jump to symbol in file |
** Project search & replace
This module provides interactive text search and replace using ripgrep.
| Keybind | Description |
|-----------+--------------------------|
| =SPC s p= | Search project |
| =SPC s P= | Search another project |
| =SPC s d= | Search this directory |
| =SPC s D= | Search another directory |
| Keybind | Description |
|---------+--------------------------|
| [[kbd:][SPC s p]] | Search project |
| [[kbd:][SPC s P]] | Search another project |
| [[kbd:][SPC s d]] | Search this directory |
| [[kbd:][SPC s D]] | Search another directory |
https://assets.doomemacs.org/completion/ivy/search.png
@ -96,7 +102,6 @@ otherwise) changes the behavior of these commands, instructing the underlying
search engine to include ignored files.
This module also provides Ex Commands for evil users:
| Ex command | Description |
|------------------------+------------------------------------------------------------------|
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
@ -108,65 +113,79 @@ commands.
-----
These keybindings are available while a search is active:
| Keybind | Description |
|---------+-----------------------------------------------|
| [[kbd:][C-c C-o]] | Open a buffer with your search results |
| [[kbd:][C-c C-e]] | Open a writable buffer of your search results |
| [[kbd:][C-SPC]] | Preview the current candidate |
| [[kbd:][C-RET]] | Open the selected candidate in other-window |
| Keybind | Description |
|-----------+-----------------------------------------------|
| =C-c C-o= | Open a buffer with your search results |
| =C-c C-e= | Open a writable buffer of your search results |
| =C-SPC= | Preview the current candidate |
| =C-RET= | Open the selected candidate in other-window |
Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed
with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil
users).
Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with
[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users).
https://assets.doomemacs.org/completion/ivy/search-replace.png
** In-buffer searching
The =swiper= package provides an interactive buffer search powered by ivy. It
The [[doom-package:][swiper]] package provides an interactive buffer search powered by ivy. It
can be invoked with:
+ =SPC s s= (~swiper-isearch~)
+ =SPC s S= (~swiper-isearch-thing-at-point~)
+ =SPC s b= (~swiper~)
+ ~:sw[iper] [QUERY]~
- [[kbd:][SPC s s]] (~swiper-isearch~)
- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~)
- [[kbd:][SPC s b]] (~swiper~)
- ~:sw[iper] [QUERY]~
https://assets.doomemacs.org/completion/ivy/swiper.png
A wgrep buffer can be opened from swiper with =C-c C-e=.
A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]].
** Ivy integration for various completing commands
*** General
| Keybind | Description |
|----------------+---------------------------|
| =M-x=, =SPC := | Smarter, smex-powered M-x |
| =SPC '= | Resume last ivy session |
| Keybind | Description |
|------------+---------------------------|
| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x |
| [[kbd:][SPC ']] | Resume last ivy session |
*** Jump to files, buffers or projects
| Keybind | Description |
|----------------------+---------------------------------------|
| =SPC RET= | Find bookmark |
| =SPC f f=, =SPC .= | Browse from current directory |
| =SPC p f=, =SPC SPC= | Find file in project |
| =SPC f r= | Find recently opened file |
| =SPC p p= | Open another project |
| =SPC b b=, =SPC ,= | Switch to buffer in current workspace |
| =SPC b B=, =SPC <= | Switch to buffer |
| Keybind | Description |
|------------------+---------------------------------------|
| [[kbd:][SPC RET]] | Find bookmark |
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
| [[kbd:][SPC f r]] | Find recently opened file |
| [[kbd:][SPC p p]] | Open another project |
| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
*** Search
| Keybind | Description |
|-----------+-------------------------------------------|
| =SPC p t= | List all TODO/FIXMEs in project |
| =SPC s b= | Search the current buffer |
| =SPC s d= | Search this directory |
| =SPC s D= | Search another directory |
| =SPC s i= | Search for symbol in current buffer |
| =SPC s p= | Search project |
| =SPC s P= | Search another project |
| =SPC s s= | Search the current buffer (incrementally) |
| Keybind | Description |
|---------+-------------------------------------------|
| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
| [[kbd:][SPC s b]] | Search the current buffer |
| [[kbd:][SPC s d]] | Search this directory |
| [[kbd:][SPC s D]] | Search another directory |
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
| [[kbd:][SPC s p]] | Search project |
| [[kbd:][SPC s P]] | Search another project |
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** TODO Enable fuzzy/non-fuzzy search for specific commands
** TODO Change the position of the ivy childframe
* TODO Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
** Helm vs Ivy vs Ido vs Vertico
See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]].
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

315
modules/completion/vertico/README.org
View file

@ -1,73 +1,66 @@
#+TITLE: completion/vertico
#+DATE: July 25, 2021
#+SINCE: v3.0.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :completion vertico
#+subtitle: Tomorrow's search engine
#+created: July 25, 2021
#+since: 21.12.0 (#4664)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#vertico-keybindings][Vertico keybindings]]
- [[#jump-to-navigation][Jump-to navigation]]
- [[#project-search--replace][Project search & replace]]
- [[#in-buffer-searching][In-buffer searching]]
- [[#vertico-integration-for-various-completing-commands][Vertico integration for various completing commands]]
- [[#general][General]]
- [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]]
- [[#search][Search]]
- [[#file-path-completion][File Path Completion]]
- [[#consult][Consult]]
- [[#multiple-candidate-search][Multiple candidate search]]
- [[#async-search-commands][Async search commands]]
- [[#marginalia][Marginalia]]
- [[#orderless-filtering][Orderless filtering]]
- [[#configuration][Configuration]]
- [[#vertico][Vertico]]
- [[#consult-1][Consult]]
- [[#marginalia-1][Marginalia]]
- [[#embark][Embark]]
* Description
* Description :unfold:
This module enhances the Emacs search and completion experience, and also
provides a united interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]].
It does this with several modular packages focused on enhancing the built-in
~completing-read~ interface, rather than replacing it with a parallel ecosystem
like =ivy= and =helm= do. The primary packages are:
like [[doom-package:][ivy]] and [[doom-package:][helm]] do. The primary packages are:
+ Vertico, which provides the vertical completion user interface
+ Consult, which provides a suite of useful commands using ~completing-read~
+ Embark, which provides a set of minibuffer actions
+ Marginalia, which provides annotations to completion candidates
+ Orderless, which provides better filtering methods
- Vertico, which provides the vertical completion user interface
- Consult, which provides a suite of useful commands using ~completing-read~
- Embark, which provides a set of minibuffer actions
- Marginalia, which provides annotations to completion candidates
- Orderless, which provides better filtering methods
** Maintainers
+ @iyefrat
- [[doom-user:][@iyefrat]]
** Module Flags
+ =+icons= Adds icons to =file= and =buffer= category completion selections.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/minad/vertico][vertico]]
+ [[https://github.com/minad/consult][consult]]
+ [[https://github.com/oantolin/embark/][embark]]
+ [[https://github.com/oantolin/embark/][embark-consult]]
+ [[https://github.com/minad/marginalia][marginalia]]
+ [[https://github.com/oantolin/orderless][orderless]]
+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]]
+ [[https://github.com/minad/consult/][consult-flycheck]] (=:checkers syntax=)
+ [[https://github.com/iyefrat/all-the-icons-completion][all-the-icons-completion]] (=+icons=)
** Module flags
- +icons ::
Add icons to =file= and =buffer= category completion selections.
* Prerequisites
Some of the advanced filtering features in async =consult= commands require
=grep= and =ripgrep= to be built with support for [[https://www.pcre.org/][PCRE]] lookahead, see [[#async-search-commands][Async
search commands]] for more information. You can check if this is true for your
machine by running ~doom doctor~.
** Packages
- [[doom-package:][all-the-icons-completion]] if [[doom-module:][+icons]]
- [[doom-package:][consult]]
- [[doom-package:][consult-flycheck]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][embark]]
- [[doom-package:][embark-consult]]
- [[doom-package:][marginalia]]
- [[doom-package:][orderless]]
- [[doom-package:][vertico]]
- [[doom-package:][wgrep]]
* Features
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]] (built with [[https://www.pcre.org/][PCRE]] support; run ~$
doom doctor~ to determine if your build meets this requirement), which is a hard
dependency of Doom itself, so you should already have it installed.
Otherwise, Consult (a plugin this module installs) provides many commands to
interface with a variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/
more. These programs are optional for this module, but must be installed if you
intend to use their associated Helm command or plugin.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
The packages in this module modify and use the built-in ~completing-read~
function, which is used by any function that requires completion. Due to this
@ -79,118 +72,117 @@ Doom-specific additions:
When in an active Vertico completion session, the following doom added
keybindings are available:
| Keybind | Description |
|-----------------------+-------------------------------------------------------------------------------|
| =C-k= | (evil) Go to previous candidate |
| =C-j= | (evil) Go to next candidate |
| =C-M-k= | (evil) Go to previous group |
| =C-M-j= | (evil) Go to next group |
| =C-;= or =<leader> a= | Open an ~embark-act~ menu to chose a useful action |
| =C-c C-;= | ~embark-export~ the current candidate list (export to a type-specific buffer) |
| =C-c C-l= | ~embark-collect~ the current candidate list (collect verbatim) |
| =C-SPC= | Preview the current candidate |
| Keybind | Description |
|-------------------+----------------------------------------------------------------|
| [[kbd:][C-k]] | (evil) Go to previous candidate |
| [[kbd:][C-j]] | (evil) Go to next candidate |
| [[kbd:][C-M-k]] | (evil) Go to previous group |
| [[kbd:][C-M-j]] | (evil) Go to next group |
| [[kbd:][C-;]] or [[kbd:][<leader> a]] | Open an ~embark-act~ menu to chose a useful action |
| [[kbd:][C-c C-;]] | export the current candidate list to a buffer |
| [[kbd:][C-c C-l]] | ~embark-collect~ the current candidate list (collect verbatim) |
| [[kbd:][C-SPC]] | Preview the current candidate |
~embark-act~ will prompt you with a =which-key= menu with useful commands on the
selected candidate or candidate list, depending on the completion category. Note
that you can press =C-h= instead of choosing a command to filter through the
that you can press [[kbd:][C-h]] instead of choosing a command to filter through the
options with a Vertico buffer, that also has slightly more detailed descriptions
due to Marginalia annotations.
** Jump-to navigation
This module provides an interface to navigate within a project using
=projectile=:
[[doom-package:][projectile]]:
https://assets.doomemacs.org/completion/vertico/projectile.png
| Keybind | Description |
|----------------------+-------------------------------------|
| =SPC p f=, =SPC SPC= | Jump to file in project |
| =SPC f f=, =SPC .= | Jump to file from current directory |
| =SPC s i= | Jump to symbol in file |
| Keybind | Description |
|------------------+-------------------------------------|
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project |
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory |
| [[kbd:][SPC s i]] | Jump to symbol in file |
** Project search & replace
This module provides interactive text search and replace using ripgrep.
| Keybind | Description |
|-----------+--------------------------|
| =SPC s p= | Search project |
| =SPC s P= | Search another project |
| =SPC s d= | Search this directory |
| =SPC s D= | Search another directory |
| Keybind | Description |
|---------+--------------------------|
| [[kbd:][<leader> s p]] | Search project |
| [[kbd:][<leader> s P]] | Search another project |
| [[kbd:][<leader> s d]] | Search this directory |
| [[kbd:][<leader> s D]] | Search another directory |
https://assets.doomemacs.org/completion/vertico/search.png
Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u=
Prefixing these keys with the universal argument ([[kbd:][SPC u]] for evil users; [[kbd:][C-u]]
otherwise) changes the behavior of these commands, instructing the underlying
search engine to include ignored files.
This module also provides Ex Commands for evil users:
| Ex command | Description |
|------------------------+------------------------------------------------------------------|
| Ex command | Description |
|----------------------+----------------------------------------------------------------|
| ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) |
| ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) |
The optional `!` is equivalent to the universal argument for the previous
The optional ~!~ is equivalent to the universal argument for the previous
commands.
-----
On top of the usual Vertico keybindings, search commands also offer support for
exporting the current candidate list to an editable buffer =C-c C-e=. After
editing the changes can be committed with =C-c C-c= and aborted with =C-c C-k=
(alternatively =ZZ= and =ZQ=, for evil users). It uses =wgrep= for grep
searches, =wdired= for file searches, and =occur= for buffer searches.
exporting the current candidate list to an editable buffer [[kbd:][C-c C-e]]. After
editing the changes can be committed with [[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]]
(alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). It uses [[doom-package:][wgrep]] for grep searches,
[[doom-package:][wdired]] for file searches, and =occur= for buffer searches.
https://assets.doomemacs.org/completion/vertico/search-replace.png
** In-buffer searching
This module provides some in buffer searching bindings:
+ =SPC s s= (~isearch~)
+ =SPC s S= (~+vertico/search-symbol-at-point~ via ~consult-line~)
+ =SPC s b= (~consult-line~)
- [[kbd:][SPC s s]] (~isearch~)
- [[kbd:][SPC s S]] (~+vertico/search-symbol-at-point~ via ~consult-line~)
- [[kbd:][SPC s b]] (~consult-line~)
https://assets.doomemacs.org/completion/vertico/buffer-search.png
An ~occur-edit~ buffer can be opened from ~consult-line~ with =C-c C-e=.
An ~occur-edit~ buffer can be opened from ~consult-line~ with [[kbd:][C-c C-e]].
** Vertico integration for various completing commands
*** General
| Keybind | Description |
|----------------+-----------------------------|
| =M-x=, =SPC := | Enhanced M-x |
| =SPC '= | Resume last Vertico session |
| Keybind | Description |
|------------+-----------------------------|
| [[kbd:][M-x]], [[kbd:][SPC :]] | Enhanced M-x |
| [[kbd:][SPC ']] | Resume last Vertico session |
*** Jump to files, buffers or projects
| Keybind | Description |
|----------------------+---------------------------------------|
| =SPC RET= | Find bookmark |
| =SPC f f=, =SPC .= | Browse from current directory |
| =SPC p f=, =SPC SPC= | Find file in project |
| =SPC f r= | Find recently opened file |
| =SPC p p= | Open another project |
| =SPC b b=, =SPC ,= | Switch to buffer in current workspace |
| =SPC b B=, =SPC <= | Switch to buffer |
| Keybind | Description |
|------------------+---------------------------------------|
| [[kbd:][SPC RET]] | Find bookmark |
| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory |
| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project |
| [[kbd:][SPC f r]] | Find recently opened file |
| [[kbd:][SPC p p]] | Open another project |
| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace |
| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer |
=SPC b b= and =SPC ,= support changing the workspace you're selecting a buffer from
[[kbd:][SPC b b]] and [[kbd:][SPC ,]] support changing the workspace you're selecting a buffer from
via [[https://github.com/minad/consult#narrowing-and-grouping][Consult narrowing]], e.g. if you're on the first workspace, you can switch to
selecting a buffer from the third workspace by typing =3 SPC= into the prompt,
or the last workspace by typing =0 SPC=.
selecting a buffer from the third workspace by typing [[kbd:][3 SPC]] into the prompt, or
the last workspace by typing [[kbd:][0 SPC]].
=SPC f f= and =SPC .= support exporting to a =wdired= buffer using =C-c C-e=.
[[kbd:][SPC f f]] and [[kbd:][SPC .]] support exporting to a [[kbd:][wdired]] buffer using [[kbd:][C-c C-e]].
*** Search
| Keybind | Description |
|-----------+-------------------------------------------|
| =SPC p t= | List all TODO/FIXMEs in project |
| =SPC s b= | Search the current buffer |
| =SPC s d= | Search this directory |
| =SPC s D= | Search another directory |
| =SPC s i= | Search for symbol in current buffer |
| =SPC s p= | Search project |
| =SPC s P= | Search another project |
| =SPC s s= | Search the current buffer (incrementally) |
| Keybind | Description |
|---------+-------------------------------------------|
| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project |
| [[kbd:][SPC s b]] | Search the current buffer |
| [[kbd:][SPC s d]] | Search this directory |
| [[kbd:][SPC s D]] | Search another directory |
| [[kbd:][SPC s i]] | Search for symbol in current buffer |
| [[kbd:][SPC s p]] | Search project |
| [[kbd:][SPC s P]] | Search another project |
| [[kbd:][SPC s s]] | Search the current buffer (incrementally) |
*** File Path Completion
Note that Emacs allows you to switch directories with shadow paths, for example
@ -206,17 +198,20 @@ This module modifies the default keybindings used in
~consult-completing-read-multiple~:
| Keybind | Description |
|---------+-------------------------------------------------------------|
| =TAB= | Select or deselect current candidate |
| =RET= | Enters selected candidates (also toggles current candidate) |
| [[kbd:][TAB]] | Select or deselect current candidate |
| [[kbd:][RET]] | Enters selected candidates (also toggles current candidate) |
*** Async search commands
:PROPERTIES:
:ID: 4ab16bf0-f9e8-4798-8632-ee7b13d2291e
:END:
Consult async commands (e.g. ~consult-ripgrep~) will have a preceding separator
character (usually =#=) before the search input. This is known as the =perl=
character (usually ~#~) before the search input. This is known as the =perl=
splitting style. Input typed after the separator will be fed to the async
command until you type a second seperator, afterwhich the candidate list will be
filtered with Emacs instead (and can be filtered using =orderless=, for
example). The specific seperator character can be changed by editing it, and
might be different if the initial input already contains =#=.
filtered with Emacs instead (and can be filtered using [[doom-package:][orderless]], for example).
The specific seperator character can be changed by editing it, and might be
different if the initial input already contains =#=.
Note that grep-like async commands translate the input (between the first and
second =#=) to an Orderless-light expression: space separated inputs are all
@ -229,11 +224,11 @@ For more information [[https://github.com/minad/consult#asynchronous-search][see
** Marginalia
| Keybind | Description |
|---------+---------------------------------|
| =M-A= | Cycle between annotation levels |
| [[kbd:][M-A]] | Cycle between annotation levels |
Marginalia annotations for symbols (e.g. =SPC h f= and =SPC h v=) come with
extra information the nature of the symbol. For the meaning of the annotations
see ~marginalia--symbol-class~.
Marginalia annotations for symbols (e.g. [[kbd:][SPC h f]] and [[kbd:][SPC h v]]) come with extra
information the nature of the symbol. For the meaning of the annotations see
~marginalia--symbol-class~.
** Orderless filtering
When using orderless to filter through candidates, the default behaviour is for
@ -246,40 +241,62 @@ first matched candidate as input. Filtering further is instead achieved by
pressing space and entering another input. In essence, when trying to match
=foobar.org=, instead of option 1., use option 2.:
1. (BAD) Enter =foo TAB=, completes to =foobar.=, enter =org RET=
2. (GOOD) Enter =foo SPC org RET=
1. (BAD) Enter ~foo TAB~, completes to =foobar.=, enter ~org RET~
2. (GOOD) Enter ~foo SPC org RET~
Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more finegrained filtering, which
Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more fine-grained filtering, which
you can use to further specify each space separated input in the following ways:
| Input | Description |
|------------------+----------------------------------------------|
| =!foo= | match without literal input =foo= |
| =%foo= or =foo%= | perform ~char-fold-to-regexp~ on input =foo= |
| =`foo= or =foo`= | match input =foo= as an initialism |
| ==foo= or =foo== | match only with literal input =foo= |
| =~foo= or =foo~= | match input =foo= with fuzzy/flex matching |
| Input | Description |
|--------------+------------------------------------------|
| ~!foo~ | match without literal input =foo= |
| ~%foo~ or ~foo%~ | perform ~char-fold-to-regexp~ on input =foo= |
| ~`foo~ or ~foo`~ | match input =foo= as an initialism |
| ~=foo~ or ~foo=~ | match only with literal input =foo= |
| ~~foo~ or ~foo~~ | match input =foo= with fuzzy/flex matching |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
If you want to further configure this module, here are some good places to
start:
* Configuration
If you want to further configure this module, here are some good places to start:
** Vertico
Vertico provides several [[https://github.com/minad/vertico#extensions][extentions]] that can be used to extend it's interface
** Consult
Much of the behaviour of Consult commands can be changed with
~consult-customize~. The =vertico= module already does this, if you want to
override the module's modifications, do:
#+begin_src emacs-lisp
(setq consult--read-config nil)
(consult-customize
;...
)
(consult-customize ...)
#+end_src
If you are changing the preview key (set to =C-SPC=), remember to change the
If you are changing the preview key (set to [[kbd:][C-SPC]]), remember to change the
binding on ~vertico-map~ as well, as the binding there gets previews to work to
an extent on non-consult commands as well.
** Marginalia
You can add more Marginalia annotation levels and change the existing ones by
editing ~marginalia-annotator-registry~
editing ~marginalia-annotator-registry~
** Embark
You can change the available commands in Embark for category ~$cat~ by editing
~embark-$cat-map~, and even add new categories. Note that you add categories
by defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them.
~embark-$cat-map~, and even add new categories. Note that you add categories by
defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
** Helm vs Ivy vs Ido vs Vertico
See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]].
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

11
modules/config/README.org Normal file
View file

@ -0,0 +1,11 @@
# -*- mode: doom-docs-org -*-
#+title: :config
#+created: July 29, 2021
#+since: 21.12.0
* Description
Modules in this category provide sane defaults or improve your ability to
configure Emacs. It is best to load these last.
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

91
modules/config/default/README.org
View file

@ -1,44 +1,69 @@
#+TITLE: :config default
# -*- mode: doom-docs-org -*-
#+title: :config default
#+subtitle: Reasonable defaults for reasonable people
#+created: February 14, 2018
#+since: 2.0.9
* Description :unfold:
This module provides a set of reasonable defaults, including:
+ A Spacemacs-esque keybinding scheme
+ Extra Ex commands for evil-mode users
+ A yasnippet snippets library tailored to Doom emacs
+ A configuration for (almost) universally repeating searches with =;= and =,=
- A Spacemacs-inspired keybinding scheme
- A configuration for (almost) universally repeating searches with [[kbd:][;]] and [[kbd:][,]]
- A [[doom-package:][smartparens]] configuration for smart completion of certain delimiters, like
~/* */~ command blocks in C-languages, ~<?php ?>~ tags in PHP, or ~def end~ in
Ruby/Crystal/etc.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +bindings :: ...
- +smartparens :: ...
** Packages
- [[doom-package:][avy]]
- [[doom-package:][drag-stuff]]
- [[doom-package:][link-hint]]
- [[doom-package:][expand-region]] unless [[doom-module:][:editor evil]]
** Hacks
- ~epa-pinentry-mode~ is set to ~'loopback~, forcing gpg-agent to use the Emacs
minibuffer when prompting for your passphrase. *Only works with GPG 2.1+!*
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
The defaults module is intended as a "reasonable-defaults" module, but also as a
reference for your own private modules. You'll find [[https://github.com/hlissner/doom-emacs-private][my private module in a
separate repo]].
Refer to the [[https://github.com/hlissner/doom-emacs/wiki/Customization][Customization page]] on the wiki for details on starting your own
private module.
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Table of Contents :TOC:
- [[#install][Install]]
- [[#configuration][Configuration]]
- [[#im-not-an-evil-user][I'm not an evil user...]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
- [[#hacks][Hacks]]
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Install
This module has no external dependencies.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Configuration
** I'm not an evil user...
That's fine. All evil configuration is ignored if =:editor evil= is disabled.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote
* Appendix
** Commands
+ ~+default/browse-project~
+ ~+default/browse-templates~
+ ~+default/find-in-templates~
+ ~+default/browse-notes~
+ ~+default/find-in-notes~
+ ~+default/find-in-snippets~
** Hacks
+ ~epa-pinentry-mode~ is set to ~'loopback~, forcing gpg-agent to use the Emacs
minibuffer when prompting for your passphrase. *Only works with GPG 2.1+!*
- ~+default/browse-project~
- ~+default/browse-templates~
- ~+default/find-in-templates~
- ~+default/browse-notes~
- ~+default/find-in-notes~
- ~+default/find-in-snippets~

135
modules/config/literate/README.org
View file

@ -1,106 +1,125 @@
#+TITLE: config/literate
#+DATE: May 4, 2020
#+SINCE: v2.0.9
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :config literate
#+subtitle: Disguise your config as poor documentation
#+created: May 28, 2020
#+since: 2.0.9
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#change-the-location-of-configorg][Change the location of config.org]]
- [[#change-where-src-blocks-are-tangled-or-prevent-it-entirely][Change where src blocks are tangled or prevent it entirely]]
- [[#troubleshooting][Troubleshooting]]
- [[#how-to-tangle-to-doomdirinitel][How to tangle to =DOOMDIR/init.el=]]
- [[#how-to-disable-tangle-on-save][How to disable tangle-on-save]]
* Description
* Description :unfold:
This module enables support for a literate config.
A literate config consists of a =DOOMDIR/config.org=. All src blocks within are
tangled =DOOMDIR/config.el=, by default, when ~doom sync~ is executed.
A literate config consists of a =$DOOMDIR/config.org=. All src blocks within are
tangled =$DOOMDIR/config.el=, by default, when ~$ doom sync~ is executed.
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
This module installs no plugins.
** Packages
/This module doesn't install any packages./
* Prerequisites
This module has no prerequisites.
** Hacks
/No hacks documented for this module./
* Features
+ Automatically tangles ~config.org~ to ~config.el~ when saving. See
Troubleshooting section belong on how to disable it.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module only requires a =$DOOMDIR/config.org=, which will be tangled into
=$DOOMDIR/config.el= when you run ~$ doom sync~.
#+begin_quote
🚧 *Be careful!* Enabling this module will overwrite =$DOOMDIR/config.el=! If
you are only trying out the module, *back up this file first!*
#+end_quote
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
- Automatically tangles =$DOOMDIR/config.org= to =$DOOMDIR/config.el= when
saving. See [[*Troubleshooting][Troubleshooting]] section belong on how to disable it.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Change the location of config.org
The ~+literate-config-file~ variable controls where to look for your config.org.
To change this it must be modified early -- in =DOOMDIR/init.el= or
=DOOMDIR/cli.el=.
To change this it must be modified early -- in =$DOOMDIR/init.el= or
=$DOOMDIR/cli.el=.
Source blocks needs to be in some language to be automatically tangled, for
example ~#+BEGIN_SRC elisp~, but it doesn't matter what language is used. All
blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax
example ~#+begin_src emacs-lisp~, but it doesn't matter what language is used.
All blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax
highlighting. If you don't want to specify language in block you can also
enforce tangling by adding ~#+BEGIN_SRC :tangle yes~
enforce tangling by adding ~#+begin_src :tangle yes~
** Change where src blocks are tangled or prevent it entirely
By default, this module tangles all src emacs-lisp blocks to config.el unless
otherwise specified.
To specify otherwise use the =:tangle= parameter to:
To specify otherwise use the ~:tangle~ parameter to:
- Specify a destination other than config.el: ~:tangle packages.el~
- Disable tangling of the block altogether with ~:tangle no~
- Or force non-elisp src blocks to tangle somewhere
For example:
#+BEGIN_SRC org
,#+BEGIN_SRC elisp :tangle no
#+begin_src org
,#+begin_src emacs-lisp :tangle no
(message "Don't tangle me")
,#+END_SRC
,#+end_src
,#+BEGIN_SRC elisp :tangle packages.el
,#+begin_src emacs-lisp :tangle packages.el
(package! my-package)
(package! other-package)
,#+END_SRC
,#+end_src
,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755)
#!/usr/bin/env bash
echo Hello world
,#+END_SRC
,#+end_src
,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash"
,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash"
echo Hello world
,#+END_SRC
#+END_SRC
,#+end_src
#+end_src
You'll find more information about babel src blocks and what parameters they
support [[https://orgmode.org/manual/Working-with-Source-Code.html][in the manual]].
support [[https://orgmode.org/manual/Working-with-Source-Code.html][in the Org manual]].
* Troubleshooting
** How to tangle to =DOOMDIR/init.el=
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
** How do I tangle to =$DOOMDIR/init.el=?
If your literate needs are more complex (e.g. you want to make your init.el
literate), this module won't cut it. =init.el= is loaded long before
=config.org= is tangled in the ~doom sync~ process.
literate), this module won't cut it. =init.el= files in modules are loaded long
before =config.org= is tangled in the ~$ doom sync~ process.
However, Doom comes with a [[file:../../../bin/org-tangle][bin/org-tangle]] script which can be used to tangle
arbitrary org files from the command line. Use it to create your own compilation
workflows. This is /much/ faster than using ~org-babel-load-file~ directly to
load your literate config every time Doom is started.
** How to disable tangle-on-save
** How do I disable tangle-on-save?
There are occasions where tangling on save may be undesirable. Maybe it's too
slow, produces too much noise, or happens too often (on unrelated org files in
your =DOOMDIR=). This behavior can be disabled with:
#+BEGIN_SRC elisp
;; add to DOOMDIR/config.el
your =$DOOMDIR=). This behavior can be disabled with:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(remove-hook 'org-mode-hook #'+literate-enable-recompile-h)
#+END_SRC
#+end_src
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

10
modules/editor/README.org Normal file
View file

@ -0,0 +1,10 @@
# -*- mode: doom-docs-org -*-
#+title: :editor
#+created: July 30, 2021
#+since: 21.12.0
* Description
For modules concerned with the insertion and editing of text. Amen.
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

282
modules/editor/evil/README.org
View file

@ -1,114 +1,114 @@
#+TITLE: editor/evil
#+DATE: February 2, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :editor evil
#+subtitle: The text editor Emacs was missing
#+created: April 08, 2020
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#ported-vim-plugins][Ported vim plugins]]
- [[#custom-text-objects][Custom Text Objects]]
- [[#custom-ex-commands][Custom Ex Commands]]
- [[#configuration][Configuration]]
- [[#removing-evil-mode][Removing evil-mode]]
- [[#restoring-old-substitution-behavior-on-ss][Restoring old substitution behavior on s/S]]
- [[#restoring-old-y-behavior-yank-the-whole-line][Restoring old Y behavior (yank the whole line)]]
- [[#disabling-cursor-movement-when-exiting-insert-mode][Disabling cursor movement when exiting insert mode]]
* Description :unfold:
This holy module brings the Vim editing model to Emacs.
* Description
This holy module brings the vim experience to Emacs.
** Maintainers
- [[doom-user:][@hlissner]]
** Module Flags
+ =+everywhere= Enables evilified keybinds everywhere possible. Uses the
[[https://github.com/emacs-evil/evil-collection][evil-collection]] plugin as a foundation.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/emacs-evil/evil][evil]]
+ [[https://github.com/wcsmith/evil-args][evil-args]]
+ [[https://github.com/PythonNut/evil-easymotion][evil-easymotion]]
+ [[https://github.com/cute-jumper/evil-embrace.el][evil-embrace]]
+ [[https://github.com/syl20bnr/evil-escape][evil-escape]]
+ [[https://github.com/Dewdrops/evil-exchange][evil-exchange]]
+ [[https://github.com/TheBB/evil-indent-plus][evil-indent-plus]]
+ [[https://github.com/edkolev/evil-lion][evil-lion]]
+ [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commentary]]
+ [[https://github.com/cofi/evil-numbers][evil-numbers]]
+ [[https://github.com/noctuid/evil-textobj-anyblock][evil-textobj-anyblock]]
+ [[https://github.com/hlissner/evil-snipe][evil-snipe]]
+ [[https://github.com/emacs-evil/evil-surround][evil-surround]]
+ [[https://github.com/alexmurray/evil-vimish-fold][evil-vimish-fold]]
+ [[https://github.com/bling/evil-visualstar][evil-visualstar]]
+ [[https://github.com/ninrod/exato][exato]]
+ [[https://github.com/emacs-evil/evil-collection][evil-collection]]*
+ [[https://www.github.com/rgrinberg/evil-quick-diff][evil-quick-diff]]
** Module flags
- +everywhere ::
Enable evilified keybinds everywhere possible. Uses the [[https://github.com/emacs-evil/evil-collection][evil-collection]] plugin
as a foundation.
** Packages
- [[doom-package:][evil]]
- [[doom-package:][evil-args]]
- [[doom-package:][evil-collection]] if [[doom-module:][+everywhere]]
- [[doom-package:][evil-easymotion]]
- [[doom-package:][evil-embrace]]
- [[doom-package:][evil-escape]]
- [[doom-package:][evil-exchange]]
- [[doom-package:][evil-indent-plus]]
- [[doom-package:][evil-lion]]
- [[doom-package:][evil-nerd-commentary]]
- [[doom-package:][evil-numbers]]
- [[doom-package:][evil-quick-diff]]
- [[doom-package:][evil-snipe]]
- [[doom-package:][evil-surround]]
- [[doom-package:][evil-textobj-anyblock]]
- [[doom-package:][evil-vimish-fold]]
- [[doom-package:][evil-visualstar]]
- [[doom-package:][exato]]
** Hacks
+ The o/O keys will respect and continue commented lines (can be disabled by
- The o/O keys will respect and continue commented lines (can be disabled by
setting ~+evil-want-o/O-to-continue-comments~ to ~nil~).
+ In visual mode, =*= and =#= will search for the current selection instead of
the word-at-point.
+ The ~:g[lobal]~ ex command has been modified to highlight matches.
+ More of vim's filename modifiers are supported in ex commands (like ~:p~,
- In visual mode, [[kbd:][*]] and [[kbd:][#]] will search for the current selection instead of the
word-at-point.
- The ~:g[lobal]~ ex command has been modified to highlight matches.
- More of vim's filename modifiers are supported in ex commands (like ~:p~,
~:p:h~ or ~:t~) than vanilla evil-mode offers.
+ A custom filename modifier is available in Doom: ~:P~, which expands to the
- A custom filename modifier is available in Doom: ~:P~, which expands to the
project root (throws an error if not in a project).
* Prerequisites
This module has no external prerequisites.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
** Ported vim plugins
The following vim plugins have been ported to evil:
| Vim Plugin | Emacs Plugin | Keybind(s) |
|-----------------------+--------------------------------+--------------------------------------------|
| vim-commentary | evil-nerd-commenter | omap =gc= |
| vim-easymotion | evil-easymotion | omap =gs= |
| vim-lion | evil-lion | omap =gl= / =gL= |
| vim-seek or vim-sneak | evil-snipe | mmap =s= / =S=, omap =z= / =Z= & =x= / =X= |
| vim-surround | evil-embrace and evil-surround | vmap =S=, omap =ys= |
| vim-unimpaired | (provided by Doom) | [[https://github.com/hlissner/doom-emacs/blob/develop/modules/editor/evil/config.el#L413-L460][see the list]] |
| Vim Plugin | Emacs Plugin | Keybind(s) |
|-----------------------+--------------------------------+--------------------------------|
| vim-commentary | evil-nerd-commenter | omap [[kbd:][gc]] |
| vim-easymotion | evil-easymotion | omap [[kbd:][gs]] |
| vim-lion | evil-lion | omap [[kbd:][gl]] / [[kbd:][gL]] |
| vim-seek or vim-sneak | evil-snipe | mmap [[kbd:][s]] / [[kbd:][S]], omap [[kbd:][z]] / [[kbd:][Z]] & [[kbd:][x]] / [[kbd:][X]] |
| vim-surround | evil-embrace and evil-surround | vmap [[kbd:][S]], omap [[kbd:][ys]] |
| vim-unimpaired | (provided by Doom) | [[https://github.com/hlissner/doom-emacs/blob/develop/modules/editor/evil/config.el#L413-L460][see the list]] |
This module has also ported vim-unimpaired keybinds to Emacs.
In other modules:
+ The tools/neotree & tools/treemacs modules provide a =NERDTree= equivalent.
+ The editor/multiple-cursors module contains functionality equal to the
- The [[doom-module:][:ui neotree]] & [[doom-module:][:ui treemacs]] modules provide a =NERDTree= equivalent.
- The [[doom-module:][:editor multiple-cursors]] module contains functionality equal to the
following vim plugins:
+ evil-multiedit => vim-multiedit
+ evil-mc => vim-multiple-cursors
- [[doom-package:][evil-multiedit]] => [[github:hlissner/vim-multiedit][vim-multiedit]]
- [[doom-package:][evil-mc]] => [[https://github.com/terryma/vim-multiple-cursors][vim-multiple-cursors]]
** Custom Text Objects
This module provides a couple extra text objects, along with the built-in ones.
For posterity, here are the built-in ones:
+ =w W= words
+ =s= sentences
+ =p= paragraphs
+ =b= parenthesized blocks
+ =b ( ) { } [ ] < >= braces, parentheses and brackets
+ =' " `= quotes
+ =t= tags
+ =o= symbols
- [[kbd:][w W]] words
- [[kbd:][s]] sentences
- [[kbd:][p]] paragraphs
- [[kbd:][b]] parenthesized blocks
- [[kbd:][b ( ) { } [ ] < >]] braces, parentheses and brackets
- [[kbd:][' " `]] quotes
- [[kbd:][t]] tags
- [[kbd:][o]] symbols
And these are text objects added by this module:
+ =a= C-style function arguments (provided by ~evil-args~)
+ =B= any block delimited by braces, parentheses or brackets (provided by
- [[kbd:][a]] C-style function arguments (provided by ~evil-args~)
- [[kbd:][B]] any block delimited by braces, parentheses or brackets (provided by
~evil-textobj-anyblock~)
+ =c= Comments
+ =f= For functions (but relies on the major mode to have sane definitions for
- [[kbd:][c]] Comments
- [[kbd:][f]] For functions (but relies on the major mode to have sane definitions for
~beginning-of-defun-function~ and ~end-of-defun-function~)
+ =g= The entire buffer
+ =i j k= by indentation (=k= includes one line above; =j= includes one line
above and below) (provided by ~evil-indent-plus~)
+ =q= For quotes (any kind)
+ =u= For URLs
+ =x= XML attributes (provided by ~exato~)
- [[kbd:][g]] The entire buffer
- [[kbd:][i j k]] by indentation ([[kbd:][k]] includes one line above; [[kbd:][j]] includes one line above and
below) (provided by ~evil-indent-plus~)
- [[kbd:][q]] For quotes (any kind)
- [[kbd:][u]] For URLs
- [[kbd:][x]] XML attributes (provided by ~exato~)
** Custom Ex Commands
| Ex Command | Description |
@ -137,64 +137,92 @@ And these are text objects added by this module:
| ~:rm[!] [PATH]~ | Delete the current buffer's file and buffer |
| ~:tcd[!]~ | Send =cd X= to tmux. X = the project root if BANG, X = ~default-directory~ otherwise |
* Configuration
** Removing evil-mode
You must do two things to remove Evil:
1. Remove =:editor evil= from =~/.doom.d/init.el=,
2. Run ~doom sync~ to clean up lingering dependencies and regenerate your
autoloads files.
3. [OPTIONAL] You may want to assign new values to ~doom-leader-alt-key~ and
~doom-localleader-alt-key~. These are bound to =C-c= and =C-c l= by default.
* TODO Configuration
#+begin_quote
Ignore ~doom-leader-key~ and ~doom-localleader-key~, they don't apply to
non-evil sessions.
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
Evil-specific configuration and keybindings (defined with ~map!~) will be
ignored without =:editor evil= present (and omitted when byte-compiling).
* Troubleshooting
[[doom-report:][Report an issue?]]
Keep in mind that, at the time of this writing, Doom was designed by a vimmer,
for vimmers. Little consideration has been put into designing a keybind scheme
for vanilla Emacs users (though it's being worked on!).
** Can't access the universal argument key ([[kbd:][C-u]])
For maximum Vim emulation, this module commandeers the C-u key for scrolling (as
it does in Vim). The same goes for [[kbd:][C-u]] in insert mode (which deletes to BOL). In
both cases the universal argument has been moved to [[kbd:][<leader> u]].
That means that much of Doom's functionality will be orphaned in an evil-less
setup. You'll have to set your own keybinds.
To undo this, use:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(setq! evil-want-C-u-scroll nil
evil-want-C-u-delete nil)
#+end_src
I suggest studying [[file:../../config/default/+emacs-bindings.el][config/default/+emacs-bindings.el]] to see what keybinds are
available for non-evil users. Otherwise, you may find inspiration [[file:../../../docs/example_configs.org][on the example
Doom configurations page]].
** Restoring old substitution behavior on s/S
Doom replaces the =s= and =S= keys with the =evil-snipe= package (a port of
** The [[kbd:][s]]/[[kbd:][S]] keys behave differently from Vim
Doom replaces the [[kbd:][s]] and [[kbd:][S]] keys with the [[doom-package:][evil-snipe]] package (a port of
vim-seek/vim-sneak for 2-character versions of f/F/t/T).
To disable evil-snipe on s/S, you can either:
1. Disable ~evil-snipe-mode~ by adding ~(remove-hook 'doom-first-input-hook
#'evil-snipe-mode)~ to =$DOOMDIR/config.el=,
2. Or disable =evil-snipe= completely with ~(package! evil-snipe :disable t)~
2. Or disable [[doom-package:][evil-snipe]] completely with ~(package! evil-snipe :disable t)~
added to =$DOOMDIR/packages.el=, but this will also disable incremental
highlighting for the f/F/t/T motions keys.
3. Or use =cl= and =cc=, respectively; they do the same thing.
** Restoring old Y behavior (yank the whole line)
Doom changes the behavior of the =Y= key in normal mode to yank-to-EOL
(equivalent to =y$=). This was to make it consistent with the =C= and =D=
capital operators, and because it was redundant with =yy=, which is easier to
type than =y$=.
3. Or use [[kbd:][cl]] and [[kbd:][cc]], respectively; they do the same thing.
** The [[kbd:][Y]] key behaves differently from Vim (should yank the whole line)
Doom changes the behavior of the [[kbd:][Y]] key in normal mode to yank-to-EOL (equivalent
to [[kbd:][y$]]). This was to make it consistent with the [[kbd:][C]] and [[kbd:][D]] capital operators, and
because it was redundant with [[kbd:][yy]], which is easier to type than [[kbd:][y$]].
If you prefer the old behavior, it can be reversed with:
#+BEGIN_SRC elisp
;; add to ~/.doom.d/config.el
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(setq! evil-want-Y-yank-to-eol nil)
#+END_SRC
** Disabling cursor movement when exiting insert mode
Vim (and evil) move the cursor one character back when exiting insert mode. If
you prefer that it didn't, set:
#+end_src
#+BEGIN_SRC elisp
;; add to ~/.doom.d/config.el
(setq evil-move-cursor-back nil)
#+END_SRC
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
** How do I remove evil?
:PROPERTIES:
:ID: f3925da6-5f0b-4d11-aa08-7bb58bea1982
:END:
1. [[id:01cffea4-3329-45e2-a892-95a384ab2338][Disable this module]].
2. Run ~$ doom sync~ to clean up lingering dependencies and regenerate your
autoloads files.
3. [OPTIONAL] Change ~doom-leader-alt-key~ and ~doom-localleader-alt-key~. These
are bound to [[kbd:][C-c]] and [[kbd:][C-c l]] by default.
#+begin_quote
🚧 Ignore ~doom-leader-key~ and ~doom-localleader-key~, they don't apply to
non-evil sessions.
#+end_quote
Evil-specific configuration and keybindings (defined with ~map!~) will be
ignored without [[doom-module:][:editor evil]] present (and omitted when byte-compiling).
** Include underscores in evil word motions?
A more in-depth answer and explanation for this can be found [[https://evil.readthedocs.io/en/latest/faq.html#underscore-is-not-a-word-character][in Evil's
documentation]].
TL;DR If you want the underscore to be recognized as word character, you can
modify its entry in the syntax-table:
#+begin_src emacs-lisp
(modify-syntax-entry ?_ "w")
#+end_src
This gives the underscore the word syntax-class. You can use a mode-hook to
modify the syntax-table in all buffers of some mode, e.g.
#+begin_src emacs-lisp
;; For python
(add-hook! 'python-mode-hook (modify-syntax-entry ?_ "w"))
;; For ruby
(add-hook! 'ruby-mode-hook (modify-syntax-entry ?_ "w"))
;; For Javascript
(add-hook! 'js2-mode-hook (modify-syntax-entry ?_ "w"))
#+end_src
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

132
modules/editor/file-templates/README.org
View file

@ -1,83 +1,97 @@
#+TITLE: editor/file-templates
#+DATE: February 11, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :editor file-templates
#+subtitle: Fill the void in your empty files
#+created: February 11, 2017
#+since: 2.0.0
* Table of Contents :TOC_2:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#usage][Usage]]
- [[#inserting-oss-licenses][Inserting OSS licenses]]
- [[#configuration][Configuration]]
- [[#registering-a-new-file-template][Registering a new file template]]
- [[#changing-existing-file-templates][Changing existing file templates]]
- [[#adding-new-oss-licenses][Adding new OSS licenses]]
- [[#troubleshooting][Troubleshooting]]
- [[#appendix][Appendix]]
- [[#api][API]]
- [[#commands][Commands]]
- [[#variables][Variables]]
* Description :unfold:
This module adds file templates for blank files, powered by [[doom-package:][yasnippet]].
* Description
This module adds file templates for blank files, powered by yasnippet.
** Maintainers
- [[doom-user:][@hlissner]]
** Module Flags
This module provides no flags.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
This module installs no plugins.
** Module flags
/This module has no flags./
* Prerequisites
This module has no prerequisites.
** Packages
/This module doesn't install any packages./
* Usage
File templates are automatically expanded when opening empty files.
** Hacks
- [[doom-package:][yasnippet]]
They are also regular yasnippet snippets, which can be expanded by typing their
trigger and pressing =TAB=. By convention, the triggers for file templates are
prefixed with two underscores ~__~.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
File templates are automatically expanded when opening empty files who match one
of the rules in the ~+file-templates-alist~ variable.
These templates are simply yasnippet snippets, which can also be expanded by
typing their trigger and pressing [[kbd:][TAB]]. By convention, the triggers for file
templates are prefixed with two underscores ~__~ (the trigger for the default
file template of a major mode is almost always ~__~).
** Inserting OSS licenses
A special command is available for inserting software licenses: ~M-x
+file-templates/insert-license~.
#+begin_quote
Licenses with a ~-bp~ suffix are boilerplate templates; shorter versions meant
for comment headers in code.
📌 Licenses with a ~-bp~ suffix are boilerplate templates; i.e. shorter
versions intended for comment headers in code files.
#+end_quote
* Configuration
** Registering a new file template
Look into the documentation of ~set-file-template!~ and ~set-file-templates!~.
** Changing existing file templates
Simply register a new template (using ~set-file-template!~) that matches the same
file. The new template would be pushed to the top of ~+file-template-alist~ and
thus would take priority while searching for a template to insert.
** Adding new OSS licenses
The ~+file-templates/insert-license~ command searches for snippets under
~text-mode~ that are named ~__license-ABC~, where ABC is the short name of the
license. e.g. ~__license-mit~.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
So long as these files exist, ~+file-templates/insert-license~ will recognize
them.
** Adding new or changing existing file templates
New file templates can be added to
=$DOOMDIR/snippets/{major-mode}/{snippet-name}=. The yasnippet documentation
covers [[https://joaotavora.github.io/yasnippet/snippet-development.html][how to write a snippet]]. You can map a snippet to a file path, major mode,
or another arbitrary predicate using [[fn:][set-file-template!]].
Look into its documentation with [[kbd:][<help> f set-file-template\!]].
** Adding new OSS licenses
Add snippet files to =$DOOMDIR/snippets/text-mode/= with the =__licenses-=
prefix and [[fn:][+file-templates/insert-license]] will recognize them. E.g.
=$DOOMDIR/snippets/text-mode/__license-mit=.
* Troubleshooting
If a file template isn't expanding where you expect it to, run ~M-x
+file-templates/debug~. This will report to you what file template rule would
apply for the correct file.
- If a file template isn't expanding where you expect it to, run ~M-x
+file-templates/debug~. This will report to you what file template rule would
apply for the correct file.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote
* Appendix
** API
+ ~set-file-template! PRED &rest PLIST~
+ ~set-file-templates! &rest TEMPLATES~
- ~set-file-template! PRED &rest PLIST~
- ~set-file-templates! &rest TEMPLATES~
** Commands
+ ~+file-templates/insert-license~
+ ~+file-templates/debug~
- ~+file-templates/insert-license~
- ~+file-templates/debug~
** Variables
+ ~+file-templates-dir~
+ ~+file-templates-default-trigger~
+ ~+file-templates-alist~
- ~+file-templates-dir~
- ~+file-templates-default-trigger~
- ~+file-templates-alist~

25
modules/editor/file-templates/autoload.el
View file

@ -96,6 +96,14 @@ evil is loaded and enabled)."
(file-relative-name path doom-private-dir))
((abbreviate-file-name path))))))
;;;###autoload
(defun +file-templates-module-for-path (&optional path)
"Generate a title for a doom module's readme at PATH."
(let ((m (doom-module-from-path (or path (buffer-file-name)))))
(if (eq (cdr m) 'README.org)
(symbol-name (car m))
(format "%s %s" (car m) (cdr m)))))
;;
;;; Commands
@ -133,3 +141,20 @@ for it. This is used for testing."
:key #'yas--template-key :test #'equal))
(message "Found %s" (cons pred plist))
(message "Found rule, but can't find associated snippet: %s" (cons pred plist)))))
;;
;;; Trigger functions
(defun +file-templates-insert-doom-docs-fn ()
"Expand one of Doom's README templates depending."
(+file-templates--expand
t :trigger
(let ((path (file-truename (buffer-file-name))))
(cond ((string-match-p "/modules/[^/]+/README\\.org$" path)
"__doom-category-readme")
((string-match-p "/modules/[^/]+/[^/]+/README\\.org$" path)
"__doom-readme")
((file-in-directory-p path doom-docs-dir)
"__doom-docs")
("__")))))

5
modules/editor/file-templates/config.el
View file

@ -71,9 +71,8 @@ don't have a :trigger property in `+file-templates-alist'.")
("/shell\\.nix$" :trigger "__shell.nix")
(nix-mode)
;; Org
("/README\\.org$"
:when +file-templates-in-emacs-dirs-p
:trigger "__doom-readme"
(doom-docs-org-mode
:trigger +file-templates-insert-doom-docs-fn
:mode org-mode)
(org-journal-mode :ignore t)
(org-mode)

10
modules/editor/file-templates/templates/org-mode/__doom-category-readme Normal file
View file

@ -0,0 +1,10 @@
# -*- mode: snippet -*-
# name: Doom category readme
# --
#+title: `(+file-templates-module-for-path)`
#+created: `(format-time-string "%B %d, %Y")`
#+since: `(car (split-string doom-version "-"))`
$0
* Description
Replace this with a description of what modules in this category are for,
including any important information (like load order constraints).

7
modules/editor/file-templates/templates/org-mode/__doom-docs Normal file
View file

@ -0,0 +1,7 @@
# -*- mode: snippet -*-
# name: Doom documentation
# --
#+title: ${1:Title}
#+subtitle: ${2:Subtitle}
$0

226
modules/editor/file-templates/templates/org-mode/__doom-readme
View file

@ -1,70 +1,194 @@
# -*- mode: snippet -*-
# name: Doom module readme
# --
#+TITLE: ${1:`(if (string-match "modules/\\([^/]+\\)/\\([^/]+\\)/.+" buffer-file-name)
(format "%s/%s"
(match-string 1 buffer-file-name)
(match-string 2 buffer-file-name))
"")`}
#+DATE: `(format (format-time-string "%B %%s, %Y") (string-to-number (format-time-string "%d")))`
#+SINCE: ${2:<replace with next tagged release version>}
#+STARTUP: inlineimages nofold
#+title: `(+file-templates-module-for-path)`
#+subtitle: <A one-line quip about this module to display in init.example.el>
#+created: `(format-time-string "%B %d, %Y")`
#+since: `(car (split-string doom-version "-"))` (#COMMIT-OR-PR-REF)
* Table of Contents :TOC_3:noexport:
* Description :unfold:
$0Replace this with a short (1-2 sentence) description of what this module does.
This is displayed in the module index.
* Description
${3:# A summary of what this module does.}
+ If possible, include a brief list of feature highlights here
+ Like code completion, syntax checking or available snippets
+ Include links to packages & external things where possible
Then a longer, multiple paragraph description goes here, which should explain
the purpose of the module and the features/technology(ies) it provides.
** Maintainers
+ @username_linked_to_gihub (Author)
+ @username_linked_to_gihub
+ @username_linked_to_gihub
- [[doom-user:][@github_username]]
- [[doom-user:][@github_username]]
- [[doom-user:][@github_username]]
# If this module has no maintainers, then...
This module has no dedicated maintainers.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+flag1= A short description of what this flag does and what it might need
when enabled.
+ =+flag2= A short description of what this flag does and what it might need
when enabled.
+ =+flag3= A short description of what this flag does and what it might need
when enabled.
# If a module has no maintainers and can't be casually maintained by Henrik
# alone, use:
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
# Otherwise, use:
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
# Flags should be in alphanumerical order.
- +bar ::
A short description of what this flag does and what it might need when
enabled.
- +childframe ::
Display X in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or tooltip. *Requires GUI
Emacs.*
- +lsp ::
Enable LSP support for ~X-mode~. Requires [[doom-module:][:tools lsp]] and a
langserver (supports A, B, and C).
# If this module has no flags, then...
This module provides no flags.
/This module has no flags./
** Plugins
# A list of linked plugins
+ [[https://orgmode.org/][org-plus-contrib]]
+ [[https://github.com/sabof/org-bullets][org-bullets]]
+ [[https://github.com/TobiasZawada/org-yt][org-yt]]
+ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=)
+ =:lang crystal=
+ [[https://github.com/brantou/ob-crystal][ob-crystal]]
+ =:lang go=
+ [[https://github.com/pope/ob-go][ob-go]]
+ =+present=
+ [[https://github.com/anler/centered-window-mode][centered-window]]
+ [[https://github.com/takaxp/org-tree-slide][org-tree-slide]]
+ [[https://gitlab.com/oer/org-re-reveal][org-re-reveal]]
# If this module has flags but you can't document them now, add a TODO to the
# heading and use:
#+begin_quote
🔨 This module has flags, but they aren't documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** Packages
- [[doom-package:][org]]
- [[doom-package:][org-contrib]] if [[doom-module:][+contrib]]
- [[doom-package:][org-bullets]] unless [[doom-module:][+bullets]]
- if [[doom-module:][+present]]
- [[doom-package:][centered-window]]
- [[doom-package:][org-tree-slide]]
- [[doom-package:][org-re-reveal]]
# If this module installs no packages, then...
/This module doesn't install any packages./
# If this module installs packages, but you can't document them now, add a TODO
# to the heading and use:
#+begin_quote
🔨 This module installs packages, but they aren't documented yet. [[doom-contrib-module:][Document
them?]]
#+end_quote
** Hacks
# A list of internal modifications to included packages; omit if unneeded
# Place a list of internal (and potentially unexpected) modifications to
# included packages:
- Fixed X which should help you do Y
- Advised Z to work harder, better, faster, stronger.
- Tricked the hobbitses into giving me the precious.
* Prerequisites
This module has no prerequisites.
# If there aren't any hacks, use:
/No hacks documented for this module./
* Features
# An in-depth list of features, how to use them, and their dependencies.
# If this module contains hacks, but you can't document them now, add a TODO to
# the heading and use:
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
* Configuration
# How to configure this module, including common problems and how to address them.
** TODO Changelog
# Do not edit this by hand. Your commits are your changelog. Commits that
# shouldn't show up should use the 'Amend: ...' trailer (see
# https://docs.doomemacs.org/-/git-conventions for details).
#
# ALSO: Version headings should be linked to the respective heading in
# docs/changelog.org.
** [[doom-tag:][v21.12.0]] [2021-12-30]
*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]]
commit BODY
*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]]
commit BODY
*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]]
commit BODY
# If no changelog is available, use:
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
# This section should describe, in-depth, how to set up this module and its
# dependencies, starting with this line:
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
# ...Then list its external requirements, if any.
This module requires:
- ...
- ...
- ...
# And finally, go into detail about how to install them.
# If there are no external requirements, use:
/This module has no external requirements./
# If there are prerequisites but you can't document them yet, add TODO to the
# heading and use:
#+begin_quote
🔨 /No installation steps have been documented./ [[doom-contrib-module:][Document them?]]
#+end_quote
* Usage
# Walk the user through how this module is used.
# If this is left empty, add TODO to the heading and use:
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
# If this section has incomplete content, add TODO to the heading and use:
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* TODO Configuration
# Walk the user through how to configure this module, including any variables it
# exposes or user-facing configuration API.
# If this is left empty, add TODO to the heading and use:
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
# If this section has incomplete content, add TODO to the heading and use:
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Troubleshooting
# Common issues and their solution, or places to look for help.
$0
# List common issues and any workarounds/solutions, or link to external resources.
[[doom-report:][Report an issue?]]
** Common issue
Solution.
** Common issue
Solution.
** Common issue
Solution.
# If this is left empty, use:
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
[[doom-suggest-faq:][Ask a question?]]
# This is for adoption, design, or niche questions. More general
# usage/configuration matters should be covered in the sections above.
** Question
Answer
** Question
Answer
** Question
Answer
# If no questions are available, use
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
# A glossary of important major modes, minor modes, commands, functions, faces,
# and variables that this module exposes. It doesn't have to be exhaustive and
# should omit explanation/documentation.
# If this is left empty, add TODO to the heading and use:
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote
# If this section has incomplete content, add TODO to the heading and use:
#+begin_quote
🔨 /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote

92
modules/editor/fold/README.org
View file

@ -1,44 +1,70 @@
#+TITLE: editor/fold
#+DATE: February 17, 2019
#+SINCE: v2.1
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :editor fold
#+subtitle: What you can't see won't hurt you
#+created: May 15, 2019
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
This module marries hideshow, vimish-fold and outline-minor-mode to bring you
* Description :unfold:
This module marries [[doom-package:][hideshow]], [[doom-package:][vimish-fold]], and ~outline-minor-mode~ to bring you
marker, indent and syntax-based code folding for as many languages as possible.
** Module Flags
This module provides no flags.
** Maintainers
- [[doom-user:][@hlissner]]
** Plugins
+ [[https://github.com/alexmurray/evil-vimish-fold][evil-vimish-fold]]
+ [[https://github.com/matsievskiysv/vimish-fold][vimish-fold]]
[[doom-contrib-maintainer:][Become a maintainer?]]
* Prerequisites
This module has no prerequisites.
** Module flags
/This module has no flags./
* Features
** Packages
- [[doom-package:][evil-vimish-fold]]
- [[doom-package:][vimish-fold]]
- if [[doom-module:][:tools tree-sitter]]
- [[doom-package:][ts-fold]]
Emacs keybinds when evil +everywhere is disabled.
| Keybind | Description |
|------------------------+---------------------------|
| =C-c C-f C-f= | Fold region |
| =C-c C-f C-u= or =C `= | Unfold region |
| =C-c C-f C-d= | Delete folded region |
| =C-c C-f C-a C-f= | Fold all regions |
| =C-c C-f C-a C-u= | Unfold all regions |
| =C-c C-a C-d= | Delete all folded regions |
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Emacs keybinds when [[doom-module:][:editor evil +everywhere]] is disabled:
| Keybind | Description |
|--------------------+---------------------------|
| [[kbd:][C-c C-f C-f]] | Fold region |
| [[kbd:][C-c C-f C-u]] or [[kbd:][C `]] | Unfold region |
| [[kbd:][C-c C-f C-d]] | Delete folded region |
| [[kbd:][C-c C-f C-a C-f]] | Fold all regions |
| [[kbd:][C-c C-f C-a C-u]] | Unfold all regions |
| [[kbd:][C-c C-a C-d]] | Delete all folded regions |
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
Sometimes an unfolded region does not fold back with =C-c C-f C-f=. To bypass this bug you must delete the folded region (=C-c C-f C-d=) and then fold it(=C-c C-f C-f=) again.
- Sometimes, an unfolded region won't fold back with [[kbd:][C-c C-f C-f]]. To bypass this
bug you must delete the folded region ([[kbd:][C-c C-f C-d]]) and then fold it ([[kbd:][C-c C-f
C-f]]) again.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

219
modules/editor/format/README.org
View file

@ -1,30 +1,16 @@
#+TITLE: editor/format
#+DATE: July 25, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :editor format
#+subtitle: Standardize your ugly code
#+created: July 26, 2020
#+since: 21.12.0
#+begin_quote
This module has been scheduled for a rewrite. Its documentation will remain
incomplete and edge cases left unpatched in the meantime. A preview of this
rewrite can be found [[https://github.com/hlissner/doom-emacs-private/tree/master/modules/editor/format][in my private config]].
🔨 This module has been scheduled for a rewrite. Its documentation will remain
incomplete and edge cases left unpatched in the meantime. A preview of this
rewrite can be found [[https://github.com/hlissner/doom-emacs-private/tree/master/modules/editor/format][in my private config]].
#+end_quote
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#automatic-reformatting-when-saving-buffers][Automatic reformatting when saving buffers]]
- [[#disabling-the-lsp-formatter][Disabling the LSP formatter]]
- [[#defining-your-own-formatters][Defining your own formatters]]
- [[#selecting-a-specific-formatter-for-a-particular-buffer][Selecting a specific formatter for a particular buffer]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module integrates code formatters into Emacs. Here are some of the
formatters that it currently supports:
@ -37,88 +23,102 @@ rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy
#+end_quote
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+onsave= Preform buffer-wide reformatting of a buffer when you save it. See
~+format-on-save-enabled-modes~ to control what major modes to (or not to)
** Module flags
- +onsave ::
Enable reformatting of a buffer when it is saved. See
[[var:][+format-on-save-enabled-modes]] to control what major modes to (or not to)
format on save.
** Plugins
+ [[https://github.com/lassik/emacs-format-all-the-code][format-all]]
** Packages
- [[doom-package:][format-all]]
** Hacks
+ format-all has been heavily modified to suit Doom's goals for this module:
+ Reformatted text is applied to the buffer by RCS patch, as to reduce its
- format-all has been heavily modified to suit Doom's goals for this module:
- Reformatted text is applied to the buffer by RCS patch, as to reduce its
affect on cursor position.
+ Adds partial formatting, i.e. you can now reformat a subset of the buffer.
+ Adds the ability to use any arbitrary formatter on the current buffer if you
pass the universal argument to ~+format/buffer~ or ~+format/region~ (i.e.
- Adds partial formatting, i.e. you can now reformat a subset of the buffer.
- Adds the ability to use any arbitrary formatter on the current buffer if you
pass the universal argument to [[fn:][+format/buffer]] or [[fn:][+format/region]] (i.e.
removes the major-mode lock on formatters).
* Prerequisites
This module depends on external programs to perform the actual formatting. These
will need to be installed for them to work. In their absence, =format-all= will
fail silently.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
+ Angular/Vue (prettier)
+ Assembly (asmfmt)
+ Bazel Starlark (buildifier)
+ BibTeX (emacs)
+ C/C++/Objective-C (clang-format)
+ Cabal (cabal-fmt)
+ Clojure/ClojureScript (node-cljfmt)
+ CMake (cmake-format)
+ Crystal (crystal tool format)
+ CSS/Less/SCSS (prettier)
+ D (dfmt)
+ Dart (dartfmt)
+ Dhall (dhall format)
+ Dockerfile (dockfmt)
+ Elixir (mix format)
+ Elm (elm-format)
+ Emacs Lisp (emacs)
+ Fish Shell (fish_indent)
+ Fortran 90 (fprettify)
+ Gleam (gleam format)
+ Go (gofmt)
+ GraphQL (prettier)
+ Haskell (brittany)
+ HTML/XHTML/XML (tidy)
+ Java (clang-format)
+ JavaScript/JSON/JSX (prettier)
+ Jsonnet (jsonnetfmt)
+ Kotlin (ktlint)
+ LaTeX (latexindent)
+ Ledger (ledger-mode)
+ Lua (lua-fmt)
+ Markdown (prettier)
+ Nix (nixfmt)
+ OCaml (ocp-indent)
+ Perl (perltidy)
+ PHP (prettier plugin-php)
+ Protocol Buffers (clang-format)
+ PureScript (purty)
+ Python (black)
+ R (styler)
+ Ruby (rufo)
+ Rust (rustfmt)
+ Scala (scalafmt)
+ Shell script (shfmt)
+ Snakemake (snakefmt)
+ Solidity (prettier-plugin-solidity)
+ SQL (sqlformat)
+ Swift (swiftformat)
+ Terraform (terraform fmt)
+ TOML (prettier-plugin-toml)
+ TypeScript/TSX (prettier)
+ Verilog (iStyle)
+ YAML (prettier)
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
This module has no direct requirements, but each language will need one of their
supported formatter programs in order for this to work. In their absence,
[[doom-package:][format-all]] will fail silently.
Supported formatters:
- Angular/Vue (prettier)
- Assembly (asmfmt)
- Bazel Starlark (buildifier)
- BibTeX (emacs)
- C/C++/Objective-C (clang-format)
- Cabal (cabal-fmt)
- Clojure/ClojureScript (node-cljfmt)
- CMake (cmake-format)
- Crystal (crystal tool format)
- CSS/Less/SCSS (prettier)
- D (dfmt)
- Dart (dartfmt)
- Dhall (dhall format)
- Dockerfile (dockfmt)
- Elixir (mix format)
- Elm (elm-format)
- Emacs Lisp (emacs)
- Fish Shell (fish_indent)
- Fortran 90 (fprettify)
- Gleam (gleam format)
- Go (gofmt)
- GraphQL (prettier)
- Haskell (brittany)
- HTML/XHTML/XML (tidy)
- Java (clang-format)
- JavaScript/JSON/JSX (prettier)
- Jsonnet (jsonnetfmt)
- Kotlin (ktlint)
- LaTeX (latexindent)
- Ledger (ledger-mode)
- Lua (lua-fmt)
- Markdown (prettier)
- Nix (nixfmt)
- OCaml (ocp-indent)
- Perl (perltidy)
- PHP (prettier plugin-php)
- Protocol Buffers (clang-format)
- PureScript (purty)
- Python (black)
- R (styler)
- Ruby (rufo)
- Rust (rustfmt)
- Scala (scalafmt)
- Shell script (shfmt)
- Snakemake (snakefmt)
- Solidity (prettier-plugin-solidity)
- SQL (sqlformat)
- Swift (swiftformat)
- Terraform (terraform fmt)
- TOML (prettier-plugin-toml)
- TypeScript/TSX (prettier)
- Verilog (iStyle)
- YAML (prettier)
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Automatic reformatting when saving buffers
There are two ways to achieve this. Either through the =+onsave= flag, or by
adding ~format-all-mode~ to the hook of each major mode you want this behavior
@ -128,29 +128,29 @@ If you choose the former, what modes it applies to can be changed by modifying
~+format-on-save-enabled-modes~, which contains a list of major modes. If the
first item in the list is the symbol ~not~, the list is negated. This is its
default value:
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(setq +format-on-save-enabled-modes
'(not emacs-lisp-mode ; elisp's mechanisms are good enough
sql-mode ; sqlformat is currently broken
tex-mode ; latexindent is broken
latex-mode))
#+END_SRC
#+end_src
If you want to format code when you save a buffer, but want more granular
control over which major modes this behavior is enabled in, there is an
alternative. Make sure =+onsave= is disabled before you try this:
#+BEGIN_SRC elisp
alternative. Make sure [[doom-module:][+onsave]] is disabled before you try this:
#+begin_src emacs-lisp
(add-hook 'python-mode-hook #'format-all-mode)
(add-hook 'js2-mode-hook #'format-all-mode)
#+END_SRC
#+end_src
** Disabling the LSP formatter
If you are in a buffer with ~lsp-mode~ enabled and a server that supports
=textDocument/formatting=, it will be used instead of =format-all='s formatter.
=textDocument/formatting=, it will be used instead of [[doom-package:][format-all]]'s formatter.
+ To disable this behavior universally use: ~(setq +format-with-lsp nil)~
+ To disable this behavior in one mode: ~(setq-hook! 'python-mode-hook +format-with-lsp nil)~
+ To disable this behavior in one mode: ~(setq-hook! 'python-mode-hook
+format-with-lsp nil)~
** TODO Defining your own formatters
See the ~set-formatter!~ function.
@ -158,17 +158,24 @@ See the ~set-formatter!~ function.
** TODO Selecting a specific formatter for a particular buffer
Set the buffer-local variable ~+format-with~ to the name of the formatter to
use. e.g.
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(setq-hook! 'python-mode-hook +format-with 'html-tidy)
;; Or set it to `:none' to disable formatting
(setq-hook! 'python-mode-hook +format-with :none)
#+END_SRC
#+end_src
Formatters are referred to by the name they were defined with. They can be
looked up in the ~format-all-mode-table~ hash table or in format-all's [[https://github.com/lassik/emacs-format-all-the-code/blob/master/format-all.el#L512][source
code]].
* Troubleshooting
# Common issues and their solution, or places to look for help.
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

56
modules/editor/god/README.org Normal file
View file

@ -0,0 +1,56 @@
# -*- mode: doom-docs-org -*-
#+title: :editor god
#+subtitle: IDDQD
#+created: October 13, 2021
#+since: 21.12.0
#+begin_quote
🚧 *This module is deprecated.* ~god-mode~ is EOL and no longer maintained.
#+end_quote
* Description :unfold:
Adds [[doom-package:][god-mode]] support to Doom Emacs, allowing for entering commands without
modifier keys, similar to Vim's modality, separating command mode and insert
mode.
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][god-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

81
modules/editor/lispy/README.org
View file

@ -1,18 +1,13 @@
#+TITLE: editor/lispy
#+DATE: October 27, 2018
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :editor lispy
#+subtitle: Vim for lisp, for people who don't like vim
#+created: October 27, 2018
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#prerequisites][Prerequisites]]
- [[#troubleshooting][Troubleshooting]]
- [[#mouse-wheel-and-wrapadditional-wrap-key-themes-in-tty-emacs-2573][Mouse wheel and =wrap=/=additional-wrap= key themes in TTY Emacs (#2573)]]
* Description
This module adds [[https://github.com/noctuid/lispyville][lispy]] key functionality in Lisp languages.
This includes:
* Description :unfold:
This module adds a keybind scheme for navigating and editing S-expressions in
Lisps; including S-exp awareness for Evil users. This affects the following
languages:
- Common Lisp
- Emacs Lisp
@ -23,12 +18,43 @@ This includes:
- Clojure
- [[https://fennel-lang.org][Fennel]]
If evil is enabled, lispyville would also be activated for every mode where
lispy is active
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][lispy]]
- [[doom-package:][lispyville]] if [[doom-module:][:editor evil +everywhere]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
If [[doom-module:][:editor evil]] is enabled, [[doom-package:][lispyville]] would also be activated for every mode
where [[doom-package:][lispy]] is active.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
The default key themes that are set are as follows:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
'((operators normal)
c-w
(prettify insert)
@ -36,18 +62,25 @@ The default key themes that are set are as follows:
slurp/barf-lispy
additional
additional-insert)
#+END_SRC
#+end_src
To change the key themes set ~lispyville-key-theme~. Think of
~lispyville-key-theme~ as the equivalent of ~parinfer-extensions~. See
lispyville's [[https://github.com/noctuid/lispyville/blob/master/README.org][README]] for more info on the specific keybindings of each key theme
(starting [[https://github.com/noctuid/lispyville#operators-key-theme][here]]).
* Prerequisites
This module has no prerequisites.
* Troubleshooting
[[doom-report:][Report an issue?]]
** Mouse wheel and =wrap=/=additional-wrap= key themes in TTY Emacs ([[https://github.com/hlissner/doom-emacs/issues/2573][#2573]])
lispyville binds =M-[= to ~lispyville-wrap-brackets~ when the =wrap= or
=additional-wrap= key theme are enabled. In terminal Emacs, this is the key
lispyville binds [[kbd:][M-[]] to ~lispyville-wrap-brackets~ when the =wrap= or
=additional-wrap= key themes are enabled. In terminal Emacs, this is the key
Emacs receives when you scroll with your mouse wheel.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

79
modules/editor/multiple-cursors/README.org Normal file
View file

@ -0,0 +1,79 @@
# -*- mode: doom-docs-org -*-
#+title: :editor multiple-cursors
#+subtitle: Make all your mistakes at once
#+created: October 13, 2021
#+since: 21.12.0
* Description :unfold:
This module adds a multiple cursors implementation to Emacs (two, if you use
evil) that loosely take after multi-cursors in Atom or Sublime Text.
** Maintainers
- [[doom-user:][@hlissner]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- if [[doom-module:][:editor evil]]
- [[doom-package:][evil-multiedit]]
- [[doom-package:][evil-mc]]
- else
- [[doom-package:][multiple-cursors]]
** Hacks
- Attempts to smooth over [[doom-package:][multiple-cursors]]' incompatibilities with [[doom-package:][evil]], which
is used internally in some third party plugins.
- Attempts to smooth over [[doom-package:][evil-mc]]'s incompatibilities with other packages, like
[[doom-package:][lispy]].
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** evil-mc
- The [[doom-package:][evil-mc]] keys are under the [[kbd:][gz]] prefix, e.g.
- [[kbd:][gzz]] to toggle new (frozen) cursors at point.
- [[kbd:][gzt]] to toggle mirroring on and off (or switch to insert mode to activate
them).
- [[kbd:][gzA]] to place cursors at the end of each selected line.
- [[kbd:][gzI]] will place them at the beginning.
- There's also the ex command ~:mc/REGEXP/FLAGS~, for laying down cursors by
regex.
** evil-multiedit
Designates "interactive edit" regions. Only the textual changes to them are mirrored.
- [[kbd:][M-d]] to iedit the symbol at point. Again to iedit its next match.
- [[kbd:][M-S-d]] to do it backwards.
- [[kbd:][R]] (in visual mode) to iedit all matches of the selection at point in the
buffer.
- Or ~:iedit/REGEX~ to iedit all matches of REGEX.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

76
modules/editor/objed/README.org
View file

@ -1,23 +1,61 @@
#+TITLE: editor/objed
#+DATE: May 30, 2019
#+SINCE: v2.1
# -*- mode: doom-docs-org -*-
#+title: :editor objed
#+subtitle: Text object editing for the innocent
#+created: May 30, 2019
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
* Description
This modules adds [[https://github.com/clemera/objed][objed]], a global minor-mode for navigating and manipulating
text objects. It combines the ideas of versor-mode and other editors like Vim or
Kakoune and tries to align them with regular Emacs conventions.
#+begin_quote
This module is incompatible with the =:editor evil=. Enabling them both will
cause errors.
#+end_quote
* Description :unfold:
This modules adds [[doom-package:][objed]], a global minor-mode for navigating and manipulating
text objects. It combines the ideas of ~versor-mode~ and other editors like Vim
or Kakoune and tries to align them with regular Emacs conventions.
[[https://github.com/clemera/objed][See the objed project README]] for information on keybinds and usage.
** Module Flags
+ ~+manual~ Do not turn =objed= automatically. The user is responsible for calling
`objed-activate` (bound to `M-SPC` if using the default Emacs bindings.)
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +manual ::
Don't activate [[doom-package:][objed]] at startup, automatically, leaving it to the user to call
[[fn:][objed-activate]] (bound to [[kbd:][M-SPC]] if using [[doom-module:][:config default +bindings]]).
** Packages
- [[doom-package:][objed]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
#+begin_quote
🚧 This module is incompatible with [[doom-module:][:editor evil]]. Do not enable them both at
the same time or you will get errors.
#+end_quote
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

77
modules/editor/parinfer/README.org
View file

@ -1,55 +1,58 @@
#+TITLE: editor/parinfer
#+DATE: June 9, 2018
#+SINCE: v2.1
#+STARTUP: inlineimages nofold
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#keybindings][Keybindings]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
# -*- mode: doom-docs-org -*-
#+title: :editor parinfer
#+subtitle: For lispers that like Python more (i.e. nobody)
#+created: February 27, 2021
#+since: 21.12.0
* Description :unfold:
Parinfer is a minor mode that aids the writing of Lisp code. It automatically
infers parenthesis matching and indentation alignment, keeping your code
balanced and beautiful.
Note that the original =parinfer-mode= has been deprecated and superceded by
=parinfer-rust-mode=, which has much better performance.
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
This module has no dedicated maintainers.
** Module flags
/This module has no flags./
** Module Flags
** Packages
- [[doom-package:][parinfer-rust-mode]]
This module provides no flags.
** Hacks
/No hacks documented for this module./
** Plugins
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
+ [[https://github.com/justinbarclay/parinfer-rust-mode][parinfer-rust-mode]]
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prerequisites
This module requires [[https://github.com/justinbarclay/parinfer-rust-mode#parinfer-rust-library][parinfer-rust]].
This module has no prerequisites.
* Features
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Keybindings
| Binding | Description |
|-----------------+-------------------------------------------|
| [[kbd:][<localleader> p]] | Toggle between different inference modes. |
| [[kbd:][<localleader> P]] | Temporarily disable parinfer. |
| Binding | Description |
|-------------------+-------------------------------------------|
| ~<localleader> m p~ | Toggle between different inference modes. |
| ~<localleader> m P~ | Temporarily disable parinfer. |
* Configuration
# How to configure this module, including common problems and how to address them.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
# Common issues and their solution, or places to look for help.
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

98
modules/editor/rotate-text/README.org
View file

@ -1,52 +1,78 @@
#+TITLE: editor/rotate-text
#+DATE: October 14, 2021
#+SINCE: v2.0.4
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :editor rotate-text
#+subtitle: The only back'n'forth nerds will ever know
#+created: June 22, 2018
#+since: 2.0.4
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
* Description
# A summary of what this module does.
Provides a convenient way to rotate trough a set of related entities using a single key binding. There are both globally available sets as well as mode local once. For example the sequence ~enable~ and ~disable~ is globally available whereas the sequence ~public~, ~protected~ and ~private~ is only available in ~c++~ mode.
* Description :unfold:
This module adds text rotation to Doom Emacs. I.e. The ability to cycle through
keywords or text patterns at point, like ~true~ and ~false~, or ~public~,
~protected~, and ~private~ (in ~c++-mode~).
** Maintainers
# If this module has no maintainers, then...
This module has no dedicated maintainers.
- [[doom-user:][@hlissner]]
** Module Flags
# If this module has no flags, then...
This module provides no flags.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/debug-ito/rotate-text.el][rotate-text.el]]
** Module flags
/This module has no flags./
* Prerequisites
This module has no prerequisites.
** Packages
- [[doom-package:][rotate-text]]
* Features
# An in-depth list of features, how to use them, and their dependencies.
With point on a word or symbol that is part of a sequence you can call ~rotate-text~ or ~rotate-text-backward~ to rotate to the next or previous item in the sequence. The list of items will wrap around as you cycle through them.
** Hacks
/No hacks documented for this module./
* Configuration
To enable a set of items to cycle through globally, add the following to your configuration
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
For evil users: [[kbd:][[r]] and [[kbd:][]r]] will cycle back and forward (respectively) through
specified patterns for the text at point. Patterns will wrap around as you cycle
through them.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
To enable a set of items to cycle through globally:
#+begin_src emacs-lisp
;; in ~/.doom.d/config.el
;; in $DOOMDIR/config.el
(after! rotate-text
(pushnew! rotate-text-words '("small" "medium" "large")))
(add-to-list 'rotate-text-words '("small" "medium" "large")))
#+end_src
To add a sequence to a specific mode, you can add something like the following to your configuration
To add a sequence to a specific mode:
#+begin_src emacs-lisp
;; in ~/.doom.d/config.el
;; in $DOOMDIR/config.el
(set-rotate-patterns! 'c++-mode
:words '(("float" "double")))
#+end_src
#+end_src
When configuring a sequence of words or symbols that should be rotated through, it is important that all items are all lower case. The casing will be determined by the item that initiated the rotation. For example, ~Small~ will be replaced with ~Medium~ and ~SMALL~ will be replaced with ~MEDIUM~ using the example described above.
When configuring a sequence of words or symbols that should be rotated through,
it is important that all items are all lower case. The casing will be determined
by the item that initiated the rotation. For example, ~Small~ will be replaced
with ~Medium~ and ~SMALL~ will be replaced with ~MEDIUM~ using the example
described above.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

85
modules/editor/snippets/README.org
View file

@ -1,46 +1,67 @@
#+TITLE: editor/snippets
#+DATE: February 11, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :editor snippets
#+subtitle: My elves type so I don't have to
#+created: February 11, 2017
#+since: 2.0.0
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#disabling-the-built-in-snippets][Disabling the built-in snippets]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module adds snippet expansions to Emacs, powered by [[doom-package:][yasnippet]].
* Description
This module adds snippets to Emacs, powered by yasnippet.
** Maintainers
- [[doom-user:][@hlissner]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module exposes no flags.
** Module flags
/This module exposes no flags./
** Plugins
+ [[https://github.com/joaotavora/yasnippet][yasnippet]]
+ [[https://github.com/abo-abo/auto-yasnippet][auto-yasnippet]]
+ [[https://github.com/hlissner/doom-snippets][doom-snippets]]
** Packages
- [[doom-package:][yasnippet]]
- [[doom-package:][auto-yasnippet]]
- [[doom-package:][doom-snippets]]
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
* Prerequisites
This module has no external dependencies.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Features
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Disabling the built-in snippets
Don't want to use provided one? Then add this to your private module,
#+BEGIN_SRC emacs-lisp
;; in ~/.doom.d/packages.el
#+begin_src emacs-lisp
;; in $DOOMDIR/packages.el
(package! doom-snippets :ignore t)
;; If you want to replace it with yasnippet's default snippets
(package! yasnippet-snippets)
#+END_SRC
#+end_src
* TODO Troubleshooting
** Adding custom snippets
Custom snippets should be added under =$DOOMDIR/snippets/= directory. Refer to [[http://joaotavora.github.io/yasnippet/snippet-development.html][yasnippet-documentation]] on how to write snippets.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

133
modules/editor/word-wrap/README.org
View file

@ -1,17 +1,80 @@
#+TITLE: editor/word-wrap
#+DATE: August 26, 2019
#+SINCE: v2.1
# -*- mode: doom-docs-org -*-
#+title: :editor word-wrap
#+subtitle: Soft-wrapping with language-aware indent
#+created: August 25, 2019
#+since: 21.12.0 (#1709)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#configuration][Configuration]]
* Description
This module adds a minor-mode ~+word-wrap-mode~, which intelligently wraps long
* Description :unfold:
This module adds a minor-mode [[fn:][+word-wrap-mode]], which intelligently wraps long
lines in the buffer without modifying the buffer content.
** Maintainers
- [[doom-user:][@flatwhatson]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][adaptive-wrap]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Activation
Word wrapping is not enabled by default.
Wrapping can be toggled in the current buffer with ~M-x +word-wrap-mode~. The
default doom bindings bind this to [[kbd:][SPC t w]] for ~evil~ users.
To enable wrapping in a specific mode, add it to the appropriate hook in your
~config.el~:
#+begin_src emacs-lisp
;; enable word-wrap in C/C++/ObjC/Java
(add-hook 'c-mode-common-hook #'+word-wrap-mode)
#+end_src
To customize the behaviour in a specific mode:
#+begin_src emacs-lisp
;; use a single indent in json-mode
(add-hook! 'json-mode-hook
(setq-local +word-wrap-extra-indent 'single)
(+word-wrap-mode +1))
#+end_src
To turn on word wrapping (almost) everywhere:
#+begin_src emacs-lisp
;; enable word-wrap (almost) everywhere
(+global-word-wrap-mode +1)
#+end_src
To disable global word-wrapping in a specific mode:
#+begin_src emacs-lisp
;; disable global word-wrap in emacs-lisp-mode
(add-to-list '+word-wrap-disabled-modes 'emacs-lisp-mode)
#+end_src
** Settings
Wrapped lines will be indented to match the preceding line. In code buffers,
lines which are not inside a string or comment will have extra indentation as
determined by ~+word-wrap-extra-indent~. The default is to increase the indent
@ -37,45 +100,13 @@ The ~+word-wrap-visual-modes~ variable lists modes which should only enable
~visual-line-mode~ and not provide any prefix indentation. This is useful for
modes like ~org-mode~ which handle prefix indentation themselves.
** Module Flags
This module provides no flags.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
** Plugins
+ [[https://elpa.gnu.org/packages/adaptive-wrap.html][adaptive-wrap]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* Configuration
Word wrapping is not enabled by default.
Wrapping can be toggled in the current buffer with ~M-x +word-wrap-mode~. The
default doom bindings bind this to ~SPC t w~ for ~evil~ users.
To enable wrapping in a specific mode, add it to the appropriate hook in your
~config.el~:
#+BEGIN_SRC emacs-lisp
;; enable word-wrap in C/C++/ObjC/Java
(add-hook 'c-mode-common-hook #'+word-wrap-mode)
#+END_SRC
To customize the behaviour in a specific mode:
#+BEGIN_SRC emacs-lisp
;; use a single indent in json-mode
(add-hook! 'json-mode-hook
(setq-local +word-wrap-extra-indent 'single)
(+word-wrap-mode +1))
#+END_SRC
To turn on word wrapping (almost) everywhere:
#+BEGIN_SRC emacs-lisp
;; enable word-wrap (almost) everywhere
(+global-word-wrap-mode +1)
#+END_SRC
To disable global word-wrapping in a specific mode:
#+BEGIN_SRC emacs-lisp
;; disable global word-wrap in emacs-lisp-mode
(add-to-list '+word-wrap-disabled-modes 'emacs-lisp-mode)
#+END_SRC
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

10
modules/emacs/README.org Normal file
View file

@ -0,0 +1,10 @@
# -*- mode: doom-docs-org -*-
#+title: :emacs
#+created: August 01, 2021
#+since: 21.12.0
* Description
Modules in this category augment and extend the built-in features of Emacs.
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

104
modules/emacs/dired/README.org
View file

@ -1,49 +1,75 @@
#+TITLE: emacs/dired
#+DATE: May 27, 2018
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :emacs dired
#+subtitle: Making dired pretty [functional]
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#keybindings][Keybindings]]
- [[#ranger][Ranger]]
* Description :unfold:
This module provides reasonable defaults and augmentations for dired.
* Description
This module provides configuration for dired.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+ranger= Enables dired to be more like [[https://github.com/ranger/ranger][ranger]].
+ =+icons= Enables the display of fancy icons depending on file types in dired
buffers.
** Module flags
- +icons ::
Enables the display of fancy icons depending on file types in dired buffers.
- +ranger ::
Enables dired to be more like [[https://github.com/ranger/ranger][ranger]].
** Plugins
+ [[https://github.com/purcell/diredfl][diredfl]]
+ [[https://github.com/stsquad/dired-rsync][dired-rsync]]
+ [[https://github.com/dgutov/diff-hl/][diff-hl]]
+ [[https://github.com/yqrashawn/fd-dired][fd-dired]]
+ =+ranger=
+ [[https://github.com/ralesi/ranger.el][ranger]]
+ =+icons=
+ [[https://github.com/jtbm37/all-the-icons-dired][all-the-icons-dired]]
** Packages
- [[doom-package:][all-the-icons-dired]] if [[doom-module:][+icons]]
- [[doom-package:][diff-hl]]
- [[doom-package:][diredfl]]
- [[doom-package:][dired-rsync]]
- [[doom-package:][fd-dired]]
- [[doom-package:][ranger]] if [[doom-module:][+ranger]]
* Prerequisites
This module has no prerequisites *except on BSDs* where =GNU ls= (~gls~) is
needed for it to work properly (Doom doctor will notify you if it is missing).
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
* Keybindings
| Keybind | Description |
|-----------+------------------------------|
| =SPC f d= | Find directory with dired |
| =q= | Exit dired buffer |
| =C-c C-r= | Run =dired-rsync= |
| =C-c C-e= | Rename entries with =wdired= |
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module has no requirements *except on BSDs* like MacOS or FreeBSD, where
=GNU ls= (aka ~gls~) is required.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
| Keybind | Description |
|---------+----------------------------|
| [[kbd:][SPC f d]] | Find directory with dired |
| [[kbd:][q]] | Exit dired buffer |
| [[kbd:][C-c C-r]] | Run [[doom-package:][dired-rsync]] |
| [[kbd:][C-c C-e]] | Rename entries with [[doom-package:][wdired]] |
Other keybindings can be found on the official [[https://www.gnu.org/software/emacs/refcards/pdf/dired-ref.pdf][Dired reference card]].
** Ranger
If =+ranger= is enabled often a buffer will be opened in minimal ranger mode
(deer-mode). In this case =z P= can be used to toggle between full ranger and
deer-mode.
If [[doom-module:][+ranger]] is enabled often a buffer will be opened in minimal ranger mode
(~deer-mode~). In this case [[kbd:][z P]] can be used to toggle between full ranger and
~deer-mode~.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

55
modules/emacs/electric/README.org Normal file
View file

@ -0,0 +1,55 @@
# -*- mode: doom-docs-org -*-
#+title: :emacs electric
#+subtitle: Shocking keyword-based electric-indent
#+created: February 21, 2017
#+since: 2.0.0
* Description :unfold:
This module augments the built-in [[doom-package:][electric]] package with keyword-based
indentation (as opposed to character-based).
** Maintainers
- [[doom-user:][@hlissner]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
/This module doesn't install any packages./
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

74
modules/emacs/ibuffer/README.org
View file

@ -1,36 +1,58 @@
#+TITLE: emacs/ibuffer
#+DATE: October 20, 2019
#+SINCE: v2.1.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :emacs ibuffer
#+subtitle: Edit me like one of your French buffers
#+created: October 20, 2019
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module augments the built-in [[doom-package:][ibuffer]] package.
* Description
This module augments ibuffer.
- Adds project-based grouping of buffers
- Support for file-type icons
- Uses human-readable file-size
+ Adds project-based grouping of buffers
+ Support for file-type icons
+ Uses human-readable file-size
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+icons= Enables filetype icons for buffers
** Module flags
- +icons ::
Enable filetype icons for buffers using [[doom-package:][all-the-icons]].
** Plugins
+ [[https://github.com/purcell/ibuffer-projectile][ibuffer-projectile]]
+ [[https://github.com/purcell/ibuffer-vc][ibuffer-vc]]
** Packages
- [[doom-package:][ibuffer-projectile]]
- [[doom-package:][ibuffer-vc]]
* Prerequisites
This module has no prerequisites.
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
* TODO Features
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

108
modules/emacs/undo/README.org
View file

@ -1,68 +1,84 @@
#+TITLE: emacs/undo
#+DATE: April 13, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :emacs undo
#+subtitle: Persistent, smarter undo for your inevitable mistakes
#+created: April 14, 2020
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#disabling-persistent-undo-history][Disabling persistent undo history]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module augments Emacs' built-in undo system to be more intuitive and to
persist across Emacs sessions.
** Maintainers
This module has no dedicated maintainers.
- [[doom-user:][@hlissner]]
** Module Flags
+ =+tree= Uses ~undo-tree~ instead of ~undo-fu~, which is a little less stable,
but offers branching undo history and a visualizer for navigating it.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://gitlab.com/ideasman42/emacs-undo-fu][undo-fu]]
+ [[https://gitlab.com/ideasman42/emacs-undo-fu-session][undo-fu-session]]
+ [[https://github.com/emacsmirror/undo-tree][undo-tree]] (=+tree=)
** Module flags
- +tree ::
Uses [[doom-package:][undo-tree]] instead of [[doom-package:][undo-fu]], which is a little less stable, but offers
branching undo history and a visualizer for navigating it.
** Packages
- [[doom-package:][undo-fu]]
- [[doom-package:][undo-fu-session]]
- [[doom-package:][undo-tree]] if [[doom-module:][+tree]]
** Hacks
+ Both undo-fu and undo-tree have been modified to use zstd to compress undo
- Both undo-fu and undo-tree have been modified to use =zstd= to compress undo
history if it is available.
+ undo-tree only
+ Text properties are stripped from undo history to shrink it.
+ Undo-tree is too chatty about saving its history files. This has be
- undo-tree only
- Text properties are stripped from undo history to shrink it.
- Undo-tree is too chatty about saving its history files. This has be
"silenced". i.e. It's visible in \*Messages\*, but won't appear in your
minibuffer.
+ unfo-fu only
+ Doom defines =undo-fu-mode= to make it easier to add hooks/mode-local
- unfo-fu only
- Doom defines ~undo-fu-mode~ to make it easier to add hooks/mode-local
keybinds.
* Prerequisites
This module has no prerequisites.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Disabling persistent undo history
+ If you are using =+tree=:
#+BEGIN_SRC elisp
- If you are using [[doom-module:][+tree]]:
#+begin_src emacs-lisp
(after! undo-tree
(setq undo-tree-auto-save-history nil))
#+END_SRC
#+end_src
+ If you aren't:
#+BEGIN_SRC elisp
- If you aren't:
#+begin_src emacs-lisp
(remove-hook 'undo-fu-mode-hook #'global-undo-fu-session-mode)
#+END_SRC
#+end_src
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
[[doom-report:][Report an issue?]]
** undo-tree
- Has been known to truncate undo history unpredictably, due to Emacs' undo
cleanup imposing linear undo limits on non-linear undo tree data. Doom already
sets ~undo-limit~, ~undo-strong-limit~, and ~undo-outer-limit~ absurdly high
to mitigate this somewhat.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

83
modules/emacs/vc/README.org
View file

@ -1,42 +1,61 @@
#+TITLE: emacs/vc
#+DATE: May 23, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :emacs vc
#+subtitle: Be the difference you want to see in the fringe
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
This module augments Emacs builtin version control support and provides better integration with git
* Description :unfold:
This module augments Emacs builtin version control support and provides better
integration with =git=.
** Maintainers
This module has no dedicated maintainers.
- [[doom-user:][@hlissner]]
** Module Flags
This module provides no flags.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
# A list of linked plugins
+ [[https://github.com/rmuslimov/browse-at-remote][browse-at-remote]]
+ [[https://gitlab.com/pidu/git-timemachine][git-timemachine]]
+ [[https://github.com/magit/git-modes][gitconfig-mode]]
+ [[https://github.com/magit/git-modes][gitignore-mode]]
** Module flags
/This module has no flags./
* Prerequisites
This module has no prerequisites.
** Packages
- [[doom-package:][browse-at-remote]]
- [[doom-package:][git-timemachine]]
- [[doom-package:][gitconfig-mode]]
- [[doom-package:][gitignore-mode]]
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
** Hacks
- Allow [[doom-package:][browse-at-remote]] commands in [[doom-package:][git-timemachine]] buffers to open that file
in your browser at the visited revision.
- [[doom-package:][git-timemachine]] buffers will display revision details in the header-line,
rather than the minibuffer (easier to see).
- [[doom-package:][browse-at-remote]] will fall back to the =master= branch if target is in a
detached state.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module only requires [[https://git-scm.com/][Git]].
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
# How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

10
modules/email/README.org Normal file
View file

@ -0,0 +1,10 @@
# -*- mode: doom-docs-org -*-
#+title: :email
#+created: October 14, 2021
#+since: 21.12.0
* Description
Modules that turn Emacs in an email client.
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

261
modules/email/mu4e/README.org
View file

@ -1,79 +1,87 @@
#+TITLE: email/mu4e
#+DATE: April 8, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :email mu4e
#+subtitle: The great filter Hanson hadn't anticipated
#+created: April 08, 2017
#+since: 2.0.3
* Table of Contents :TOC:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#nixos][NixOS]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#offlineimap][offlineimap]]
- [[#mbsync][mbsync]]
- [[#fetching-your-mail-in-other-ways][Fetching your mail in other ways]]
- [[#mu-and-mu4e][mu and mu4e]]
- [[#orgmsg][OrgMsg]]
- [[#mu4e-alert][mu4e-alert]]
- [[#troubleshooting][Troubleshooting]]
- [[#no-such-file-or-directory-mu4e][=No such file or directory, mu4e=]]
- [[#void-function-org-time-add-error-on-gentoo][~(void-function org-time-add)~ error on Gentoo]]
* Description
* Description :unfold:
This module makes Emacs an email client, using [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]].
#+begin_quote
I want to live in Emacs, but as we all know, living is incomplete without email.
So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing
combined with org-mode for writing emails? /Yes please./
- Tidied mu4e headers view, with flags from [[doom-package:][all-the-icons]].
- Consistent coloring of reply depths (across compose and gnus modes).
- Prettified =mu4e:main= view.
- Cooperative locking of the =mu= process. Another Emacs instance may request
access, or grab the lock when it's available.
- [[doom-package:][org-msg]] integration with [[doom-module:][+org]], which can be toggled per-message, with revamped
style and an accent color.
- Gmail integrations with the [[doom-module:][+gmail]] flag.
- Email notifications with [[doom-package:][mu4e-alert]], and (on Linux) a customised notification
style.
It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email
via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand).
#+begin_quote
💡 I want to live in Emacs, but as we all know, living is incomplete without
email. So I prayed to the text editor gods and they (I) answered.
Emacs+evil's editing combined with org-mode for writing emails? /Yes
please./
It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my
email via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can
understand).
#+end_quote
** Maintainers
+ [[https://github.com/tecosaur][@tecosaur]]
- [[doom-user:][@tecosaur]]
** Module Flags
+ =+gmail= Enables gmail-specific configuration for mail ~To~ or ~From~ a gmail
address, or a maildir with ~gmail~ in the name.
+ =+org= Use =org-msg= for composing email in Org, then sending a multipart text
(ASCII export) and HTML message.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/iqbalansari/mu4e-alert][mu4e-alert]]
+ =+org=
+ [[https://github.com/jeremy-compostella/org-msg][org-msg]]
** Module flags
- +gmail ::
Enable gmail-specific configuration for mail ~To~ or ~From~ a gmail address,
or a maildir with ~gmail~ in the name.
- +org ::
Use [[doom-package:][org-msg]] for composing email in Org, then sending a multipart text (ASCII
export) and HTML message.
** Packages
- [[doom-package:][mu4e-alert]]
- [[doom-package:][org-msg]] if [[doom-module:][+org]]
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prerequisites
This module requires:
+ [[https://www.djcbsoftware.nl/code/mu/][mu]], to index your downloaded messages and to provide the [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]] package.
+ A program to sync your mail. This module comes with builtin support for
[[https://isync.sourceforge.io/][mbsync]] (recommended, default) or [[http://www.offlineimap.org/][offlineimap]] but you can sync mail in
other ways too.
- [[https://www.djcbsoftware.nl/code/mu/][mu]], to index your downloaded messages and to provide the [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]] package.
- A program to sync your mail. This module comes with builtin support for [[https://isync.sourceforge.io/][mbsync]]
(recommended, default) or [[http://www.offlineimap.org/][offlineimap]] but you can sync mail in other ways too.
#+name: Install Matrix
| Platform | Install command | Base packages |
|---------------+--------------------------+-------------------------|
| MacOS | ~brew install <pkgs>~ | =mu= |
| Arch | ~pacman -S <pkgs>~ | (AUR, ~yay -S~) =mu= |
| openSUSE | ~zypper install <pkgs>~ | =maildir-utils=, =mu4e= |
| Fedora | ~dnf install <pkgs>~ | =maildir-utils= |
| Debian/Ubuntu | ~apt-get install <pkgs>~ | =maildir-utils=, =mu4e= |
| Platform | Install command | Base packages |
|---------------+----------------------------+-------------------------|
| MacOS | ~$ brew install <pkgs>~ | =mu= |
| Arch | ~$ pacman -S <pkgs>~ | (AUR, ~$ yay -S~) =mu= |
| openSUSE | ~$ zypper install <pkgs>~ | =maildir-utils=, =mu4e= |
| Fedora | ~$ dnf install <pkgs>~ | =maildir-utils= |
| Debian/Ubuntu | ~$ apt-get install <pkgs>~ | =maildir-utils=, =mu4e= |
Then install either the =isync= (=mbsync=) or =offlineimap= package.
To send mail, mu4e uses [[https://www.gnu.org/software/emacs/manual/html_mono/smtpmail.html][smtpmail]] (an Emacs library) by default.
You can also run a local SMTP server like =sendmail= or =postfix=, or use an SMTP
forwarder such as =msmtp= (recommended).
To send mail, mu4e uses [[https://www.gnu.org/software/emacs/manual/html_mono/smtpmail.html][smtpmail]] (an Emacs library) by default. You can also run
a local SMTP server like =sendmail= or =postfix=, or use an SMTP forwarder such
as =msmtp= (recommended).
If you use =msmtp=, you'll likely want to add the following to your
=config.el=:
If you use =msmtp=:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(after! mu4e
(setq sendmail-program (executable-find "msmtp")
send-mail-function #'smtpmail-send-it
@ -83,42 +91,40 @@ If you use =msmtp=, you'll likely want to add the following to your
#+end_src
** NixOS
#+BEGIN_SRC nix
#+begin_src nix
environment.systemPackages = with pkgs; [
mu
# And one of the following
isync
offlineimap
];
#+END_SRC
#+end_src
[[https://github.com/Emiller88/dotfiles/blob/5eaabedf1b141c80a8d32e1b496055231476f65e/modules/shell/mail.nix][An example of setting up mbsync and mu with home-manager]]
* Features
+ Tidied mu4e headers view, with flags from =all-the-icons=
+ Consistent coloring of reply depths (across compose and gnus modes)
+ Prettified =mu4e:main= view
+ Cooperative locking of the =mu= process. Another Emacs instance may request
access, or grab the lock when it's available.
+ =org-msg= integration with =+org=, which can be toggled per-message, with revamped style and
an accent color
+ Gmail integrations with the =+gmail= flag
+ Email notifications with =mu4e-alert=, and (on Linux) a customised notification style
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** offlineimap
This module uses =mbsync= by default. To use =offlineimap=, change ~+mu4e-backend~:
#+BEGIN_SRC emacs-lisp
This module uses =mbsync= by default. To use =offlineimap=, change
~+mu4e-backend~:
#+begin_src emacs-lisp
(setq +mu4e-backend 'offlineimap)
#+END_SRC
#+end_src
Next, you need to write a configuration file for =offlineimap=. Mine can be found
[[https://github.com/hlissner/dotfiles/blob/be0dce5dae8f3cbafaac0cc44269d84b4a742c46/shell/mu/][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I
use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. You can find a *very*
detailed configuration [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][here]].
Next, you need to write a configuration file for =offlineimap=. Mine can be
found [[https://github.com/hlissner/dotfiles/blob/be0dce5dae8f3cbafaac0cc44269d84b4a742c46/shell/mu/][in my dotfiles repository]]. It is configured to download mail to
~\~/.mail~. I use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. You can find
a *very* detailed configuration [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][here]].
Next you can download your email with ~offlineimap -o~. This may take a while,
Next you can download your email with ~$ offlineimap -o~. This may take a while,
especially if you have thousands of mails.
You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.
@ -127,12 +133,12 @@ You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.
The steps needed to set up =mu4e= with =mbsync= are very similar to the ones for
[[#offlineimap][offlineimap]].
Start with writing a ~~/.mbsyncrc~. An example for Gmail can be found on
Start with writing a =~/.mbsyncrc=. An example for Gmail can be found on
[[http://pragmaticemacs.com/emacs/migrating-from-offlineimap-to-mbsync-for-mu4e/][pragmaticemacs.com]]. A non-Gmail example is available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. The [[http://isync.sourceforge.net/mbsync.html][manual
page]] contains all needed information to set up your own.
Next you can download your email with ~mbsync --all~. This may take a while, but
should be quicker than =offlineimap= ;).
Next you can download your email with ~$ mbsync --all~. This may take a while,
but should be quicker than =offlineimap= ;).
You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section.
@ -142,19 +148,20 @@ tailored =mbsync= command to just fetch the new changes.
If this is of interest, this approach can be seen [[https://tecosaur.github.io/emacs-config/config.html#fetching][in @tecosaur's config]] where
[[https://gitlab.com/shackra/goimapnotify][goimapnotify]] is used for this.
** Fetching your mail in other ways
You also have the possiblity to invoke an arbitary shell command to fetch your
mail by disabling this module's backend selection and setting the value of the
~mu4e-get-mail-command~ to the command you want to execute.
#+BEGIN_SRC emacs-lisp
~mu4e-get-mail-command~ to the command you want to execute:
#+begin_src emacs-lisp
(setq +mu4e-backend nil)
(after! mu4e
(setq mu4e-get-mail-command "your_command"))
#+END_SRC
#+end_src
If your command prompts you for a passphrase, you might want to change the value
of the ~mu4e~get-mail-password-regexp~ such that =mu4e= will recognize the
prompt and let you provide the passphrase from within Emacs.
of the ~mu4e~get-mail-password-regexp~ such that [[doom-package:][mu4e]] will recognize the prompt
and let you provide the passphrase from within Emacs.
** mu and mu4e
You should have your email downloaded already. If you have not, you need to set
@ -162,24 +169,23 @@ You should have your email downloaded already. If you have not, you need to set
Before you can use =mu4e= or the CLI program =mu=, you need to index your email
initially. How to do that differs a little depending on the version of =mu= you
use. You can check your version with ~mu --version~.
use. You can check your version with ~$ mu --version~.
For =mu= *>=1.4* you need to run two commands:
#+BEGIN_SRC sh
#+begin_src sh
mu init --maildir ~/.mail --my-address email@example.com
mu index
#+END_SRC
#+end_src
=mu= *<1.4* only requires one command:
#+BEGIN_SRC sh
mu index --maildir ~/.mail
#+END_SRC
#+begin_src sh
mu index --maildir $HOME/.mail
#+end_src
Be sure to replace ~~/.mail~ with the directory containing your mail.
Be sure to replace =$HOME/.mail= with the directory containing your mail.
Then configure Emacs to use your email address:
#+BEGIN_SRC emacs-lisp :tangle no
#+begin_src emacs-lisp
;; Each path is relative to the path of the maildir you passed to mu
(set-email-account! "bar.com"
'((mu4e-sent-folder . "/bar.com/Sent Mail")
@ -190,14 +196,13 @@ Then configure Emacs to use your email address:
(user-mail-address . "foo@bar.com") ;; only needed for mu < 1.4
(mu4e-compose-signature . "---\nYours truly\nThe Baz"))
t)
#+END_SRC
#+end_src
If you use multiple email accounts, defining them with ~set-email-account!~ will
automatically set the appropriate account context when replying to emails in
that account's maildir. ~mu4e-context-policy~ and ~mu4e-compose-context-policy~
can be modified to change context behavior when opening mu4e and composing
email:
#+begin_src emacs-lisp
(setq mu4e-context-policy 'ask-if-none
mu4e-compose-context-policy 'always-ask)
@ -209,7 +214,7 @@ you are not replying to an email to or from one of the specified aliases, you
will be prompted for an alias to send from.
*** Gmail
With the =+gmail= flag, integrations are applied which account for the different
With the [[doom-module:][+gmail]] flag, integrations are applied which account for the different
behaviour of Gmail.
The integrations are applied to addresses with /both/ "@gmail.com" in the
@ -222,8 +227,8 @@ benefit from the integrations:
("example@example.com" . "/example")))
#+end_src
If you only use Gmail, you can improve performance due to the way Gmail
presents messages over IMAP:
If you only use Gmail, you can improve performance due to the way Gmail presents
messages over IMAP:
#+begin_src emacs-lisp
;; don't need to run cleanup after indexing for gmail
(setq mu4e-index-cleanup nil
@ -238,14 +243,15 @@ as deleted: Auto-Expunge off - Wait for the client to update the server." and
folder: Move the message to the trash" for the integrations to work as expected.
** OrgMsg
With the =+org= flag, =org-msg= is installed, and ~org-msg-mode~ is enabled before
composing the first message. To disable ~org-msg-mode~ by default, simply
#+BEGIN_SRC emacs-lisp :tangle no
(setq mu4e-compose--org-msg-toggle-next nil)
#+END_SRC
With the [[doom-module:][+org]] flag, [[doom-package:][org-msg]] is installed, and ~org-msg-mode~ is enabled before
composing the first message. To disable ~org-msg-mode~ by default:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(setq +mu4e-compose-org-msg-toggle-next nil)
#+end_src
To toggle org-msg for a single message, just apply the universal argument to the
compose or reply command (=SPC u= with ~evil~, =C-u= otherwise).
compose or reply command ([[kbd:][SPC u]] with [[doom-package:][evil]], [[kbd:][C-u]] otherwise).
The accent color that Doom uses can be customised by setting
~+org-msg-accent-color~ to a CSS color string.
@ -253,35 +259,44 @@ The accent color that Doom uses can be customised by setting
** mu4e-alert
This provides notifications through the [[https://github.com/jwiegley/alert][alert]] library.
If you don't like this, simply add
If you don't like this use:
#+begin_src emacs-lisp
;; add to $DOOMDIR/packages.el
(package! mu4e-alert :disable t)
#+end_src
to your [[elisp:(find-file (expand-file-name "packages.el" doom-private-dir))][packages.el]] and it will not be used.
** Enabling automatic email fetching
By default, periodic email update is *disabled*. To enable periodic
mail retrieval/indexing, change the value of ~mu4e-update-interval~:
#+begin_src emacs-lisp
(setq mu4e-update-interval 60)
#+end_src
* Troubleshooting
[[doom-report:][Report an issue?]]
** =No such file or directory, mu4e=
You will get =No such file or directory, mu4e= errors if you don't run ~doom
You will get =No such file or directory, mu4e= errors if you don't run ~$ doom
sync~ after installing =mu= through your package manager.
Some times the the ~mu~ package does not include ~mu4e~ (*cough Ubuntu*).
if that's the case you will need to [[https://github.com/djcb/mu][install]] it and add it to your ~load-path~
you can do that by...
#+BEGIN_SRC emacs-lisp :tangle no
Some times the the ~mu~ package does not include ~mu4e~ (*cough Ubuntu*). if
that's the case you will need to [[https://github.com/djcb/mu][install]] it and add it to your ~load-path~ you
can do that by:
#+begin_src emacs-lisp
(add-to-list 'load-path "your/path/to/mu4e")
;; if you installed it using your package manager
(add-to-list 'load-path "/usr/share/emacs/site-lisp/mu4e")
;; if you built from source
(add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e")
#+END_SRC
#+end_src
If you have completely lost your install then you can use this handy command!
#+BEGIN_SRC shell
If you have completely lost your install then you can use:
#+begin_src sh
find / -type d -iname '*mu4e*'
# I recommend rerouting all of the errors to /dev/null
find / -type d -iname '*mu4e*' 2> /dev/null
#+END_SRC
#+end_src
** ~(void-function org-time-add)~ error on Gentoo
Gentoo users will see this error because [[https://gitweb.gentoo.org/repo/gentoo.git/tree/net-mail/mu/files/70mu-gentoo.el#n2][the =net-mail/mu= package eagerly loads
@ -291,3 +306,11 @@ version that Doom installs.
Later versions of the =net-mail/mu= package have [[https://gitweb.gentoo.org/repo/gentoo.git/commit/net-mail/mu?id=770e1fccb119fbce8ba6d16021a3598123f212ff][fixed this issue]], but you may
need to switch to the unstable build of =net-mail/mu= to see it.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

193
modules/email/notmuch/README.org
View file

@ -1,62 +1,60 @@
#+TITLE: email/notmuch
#+DATE: May 5, 2019
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :email notmuch
#+subtitle: Closest Emacs will ever be to multi-threaded
#+created: July 31, 2018
#+since: 21.12.0
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#macos][MacOS]]
- [[#arch-linux][Arch Linux]]
- [[#nixos][NixOS]]
- [[#opensuse][openSUSE]]
- [[#debianubuntu][Debian/Ubuntu]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#downloading-your-email][Downloading your email]]
- [[#sending-mail][Sending mail]]
- [[#customize-notmuch-hello-buffer][Customize =*notmuch-hello*= buffer]]
- [[#changing-the-notmuch-landing-page][Changing the =notmuch= landing page]]
- [[#writing-html-emails][Writing HTML Emails]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module turns Emacs into an email client using [[doom-package:][notmuch]].
* Description
This module turns Emacs into an email client using [[https://notmuchmail.org/][notmuch]].
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+org= Enables org-mime for writing HTML emails using org-mode.
+ =+afew= Enables integration with =afew=.
** Module flags
- +afew ::
Enable integration with [[https://github.com/afewmail/afew][afew]].
- +org ::
Enable [[doom-package:][org-mime]] for writing HTML emails using org-mode.
** Plugins
+ [[https://notmuchmail.org/][notmuch]]
+ [[https://github.com/org-mime/org-mime][org-mime]]* (with =+org= flag)
+ [[https://github.com/fuxialexander/counsel-notmuch][counsel-notmuch]]*
+ [[https://github.com/emacs-helm/helm-notmuch][helm-notmuch]]*
** Packages
- [[doom-package:][counsel-notmuch]] if [[doom-module:][:completion ivy]]
- [[doom-package:][helm-notmuch]] if [[doom-module:][:completion helm]]
- [[doom-package:][notmuch]]
- [[doom-package:][org-mime]]* if [[doom-module:][+org]]
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prerequisites
This module requires:
+ Either [[https://github.com/gauteh/lieer][gmailieer]] (default), [[https://isync.sourceforge.io/][mbsync]] or [[http://www.offlineimap.org/][offlineimap]] (to sync mail with)
+ [[https://notmuchmail.org/][notmuch]], to index and tag your downloaded messages.
+ [[https://github.com/afewmail/afew][afew]] , optionally to initially tag your downloaded messages.
+ Either [[https://github.com/gauteh/lieer][gmailieer]] (default), [[https://isync.sourceforge.io/][mbsync]] or [[http://www.offlineimap.org/][offlineimap]] -- to sync mail with.
+ [[https://notmuchmail.org/][notmuch]] -- to index and tag your downloaded messages.
+ [[https://github.com/afewmail/afew][afew]] -- optionally to initially tag your downloaded messages.
** TODO MacOS
** Arch Linux
Run one of the following commands.
#+BEGIN_SRC sh
Run one of the following commands:
#+begin_src sh
pacman -S isync notmuch #mbsync
#+END_SRC
#+BEGIN_SRC sh
#+end_src
#+begin_src sh
pacman -S offlineimap notmuch
#+END_SRC
#+end_src
See: [[https://wiki.archlinux.org/index.php/Notmuch][Arch Wiki - Notmuch]]
** NixOS
#+BEGIN_SRC nix
#+begin_src nix
environment.systemPackages = with pkgs; [
notmuch
# And one of the following
@ -64,20 +62,28 @@ environment.systemPackages = with pkgs; [
isync
offlineimap
];
#+END_SRC
#+end_src
[[https://github.com/Emiller88/dotfiles/blob/319841bd3b89e59b01d169137cceee3183aba4fc/modules/shell/mail.nix][An example of setting up mbsync and notmuch with home-manager]]
** TODO openSUSE
** TODO Debian/Ubuntu
* Features
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
| Keymap | Command | Description |
| ~SPC m u~ | =+notmuch/update= | Download, sync, and index emails with notmuch |
| ~SPC m c~ | =+notmuch/compose= | Compose new email |
| Keymap | Command | Description |
|-----------------+--------------------+-----------------------------------------------|
| [[kbd:][<localleader> u]] | ~+notmuch/update~ | Download, sync, and index emails with notmuch |
| [[kbd:][<localleader> c]] | ~+notmuch/compose~ | Compose new email |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Downloading your email
To download your email you need a sync backend. Out of the box, this module
supports =Gmailier= (the default), =mbsync=, and =offlineimap= (ordered by
@ -86,109 +92,118 @@ through setting them up with notmuch.
Later, once you've set up a sync backend and downloaded your email, you must
index your email for the first time:
#+BEGIN_SRC sh
#+begin_src sh
notmuch new
#+END_SRC
#+end_src
*** lieer
[[https://github.com/gauteh/lieer][Lieer]], formerly called Gmailieer, is the indexing tool used by default. To install lieer, see the [[https://github.com/gauteh/lieer#installation][installation docs]].
[[https://github.com/gauteh/lieer][Lieer]], formerly called Gmailieer, is the indexing tool used by default. To
install lieer, see the [[https://github.com/gauteh/lieer#installation][installation docs]].
*** offlineimap
To use [[https://www.offlineimap.org/][offlineimap]], change ~+notmuch-sync-backend~:
#+BEGIN_SRC emacs-lisp
;; add to ~/.doom.d/config.el
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(setq +notmuch-sync-backend 'offlineimap)
#+END_SRC
#+end_src
Next, write a configuration file for =offlineimap=. [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][Here is a comprehensive
example]] and [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf.minimal][another minimal one]].
As a real world example, [[https://github.com/hlissner/dotfiles/blob/5f146b6c39552c0cf38025406f5dba7389542b0a/shell/mu/.offlineimaprc][here is my old config]], where it is configured to
download mail to ~\~/.mail~. I used [[https://www.passwordstore.org/][unix pass]] to securely store my login
download mail to =$HOME/.mail=. I used [[https://www.passwordstore.org/][unix pass]] to securely store my login
credentials.
Finally, download your email with ~offlineimap -o~. This may take a while,
Finally, download your email with ~$ offlineimap -o~. This may take a while,
especially if you have thousands of emails.
*** mbsync
To use [[https://isync.sourceforge.io/][mbsync]], change ~+notmuch-sync-backend~:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(setq +notmuch-sync-backend 'mbsync)
;; Use `mbsync-xdg' if your mbsync config lives in $XDG_CONFIG_HOME/isync:
(setq +notmuch-sync-backend 'mbsync-xdg)
#+END_SRC
#+end_src
The steps needed to set up =notmuch= with =mbsync= are similar to the ones for
[[*offlineimap][offlineimap]].
Start with writing a ~\~/.mbsyncrc~ to store your configuration. An example for
GMAIL can be found on the [[https://wiki.archlinux.org/index.php/isync#Configuring][ArchWiki]] which will also explain how its integration
with notmuch for auto synchronization. A non-GMAIL example is available as a
gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]].
Start with writing a =$HOME/.mbsyncrc= to store your configuration. An example
for GMAIL can be found on the [[https://wiki.archlinux.org/index.php/isync#Configuring][ArchWiki]] which will also explain how its
integration with notmuch for auto synchronization. A non-GMAIL example is
available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]].
Finally, download your email with ~mbsync --all~. This may take a while, but
Finally, download your email with ~$ mbsync --all~. This may take a while, but
will be quicker than =offlineimap=.
*** Custom method
If you have a unique method for synchronizing your email, you can define your
own backend:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(setq +notmuch-sync-backend 'custom
;; Set this to an arbitrary shell command
+notmuch-sync-command "my-notmuch-sync-cmd")
#+END_SRC
#+end_src
** Sending mail
- [[https://notmuchmail.org/notmuch-emacs/#index6h2][notmuch docs: Sending mail]]
- [[https://notmuchmail.org/emacstips/#index11h2][notmuch docs: msmtp, message mode and multiple accounts]]
- [[https://notmuchmail.org/emacstips/#index12h2][notmuch docs: sending mail using smtpmail]]
** Customize =*notmuch-hello*= buffer
It is possible to change the =*notmuch-hello*= buffer if you want to.
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(after! notmuch
(setq notmuch-show-log nil
notmuch-hello-sections `(notmuch-hello-insert-saved-searches
notmuch-hello-insert-alltags)
;; To hide headers while composing an email
notmuch-message-headers-visible nil))
#+END_SRC
#+end_src
** Changing the =notmuch= landing page
You may want to forego the =*notmuch-hello*= buffer by having ~M-x =notmuch~ or
~SPC o m~ take you straight to a search page.
[[kbd:][<leader> o m]] take you straight to a search page.
When using ~SPC o m~ the =+notmuch-home-function= is called. By default it uses
the =notmuch= function and so has the same familiar behavior of running a
When using [[kbd:][<leader> o m]] the ~+notmuch-home-function~ is called. By default it
uses the ~notmuch~ function and so has the same familiar behavior of running a
vanilla install of notmuch-emacs. But, by overwriting this function you can run
a custom search as your landing page.
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(setq +notmuch-home-function (lambda () (notmuch-search "tag:inbox")))
#+END_SRC
#+end_src
** Writing HTML Emails
The [[https://github.com/org-mime/org-mime][org-mime]] package provides functionality for composing emails in org-mode and transforming them to HTML. This feature is enabled using the =+org= flag.
The [[https://github.com/org-mime/org-mime][org-mime]] package provides functionality for composing emails in org-mode and
transforming them to HTML. This feature is enabled using the =+org= flag.
Example use cases:
- To convert an email to an HTML email use ~M-x org-mime-htmlize~.
- To compose email using an org-mode editor buffer, use ~M-x
org-mime-edit-mail-in-org-mode~.
- To convert an email to an HTML email use ~M-x org-mime-htmlize~
- To compose email using an org-mode editor buffer, use ~M-x org-mime-edit-mail-in-org-mode~
If you'd like to make configuration changes to =org-mime=, you may do so normally. By default the output of =org-mime-htmlize= includes section numbers, a byline, and a table of contents. That's probably more formal than the emails you're used to sending, so here's some example configuration that turns those features off.
/config.el/
If you'd like to make configuration changes to =org-mime=, you may do so
normally. By default the output of =org-mime-htmlize= includes section numbers,
a byline, and a table of contents. That's probably more formal than the emails
you're used to sending, so here's some example configuration that turns those
features off:
#+begin_src emacs-lisp
;; add to $DOOMDIR/config.el
(after! org-mime
(setq org-mime-export-options '(:section-numbers nil
:with-author nil
:with-toc nil)))
#+end_src
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* TODO Troubleshooting
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

55
modules/email/wanderlust/README.org Normal file
View file

@ -0,0 +1,55 @@
# -*- mode: doom-docs-org -*-
#+title: :email wanderlust
#+subtitle: To boldly go where no mail has gone before
#+created: May 05, 2019
#+since: 21.12.0
* Description :unfold:
#+begin_quote
🔨 This module has no description. [[doom-contrib-module:][Write one?]]
#+end_quote
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +gmail ::
Enable gmail-specific configuration for mail ~To~ or ~From~ a gmail address.
** Packages
- [[doom-package:][wanderlust]]
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

11
modules/input/README.org Normal file
View file

@ -0,0 +1,11 @@
# -*- mode: doom-docs-org -*-
#+title: :input
#+created: May 13, 2019
#+since: 2.0.9
* Description
Modules in this category extend Emacs support for additional keyboard layouts
and input methods for non-English languages.
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

83
modules/input/chinese/README.org
View file

@ -1,51 +1,66 @@
#+TITLE: input/chinese
#+DATE: May 13, 2019
#+SINCE: 2.1
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :input chinese
#+subtitle: Spend your 3 hours a week in Emacs
#+created: May 13, 2019
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#using-fcitx5][Using fcitx5]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds support for traditional Chinese script by introducing two input
methods: Pinyin and Wubi.
#+begin_quote
Because I am unable to personally test this module, help to improve this module
would be greatly appreciated! Especially where performance is concerned.
#+end_quote
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
+ [[https://github.com/tumashu/pyim][pyim]] (unless =+wubi=)
+ [[https://github.com/zilongshanren/chinese-wbim][chinese-wbim]] (if =+wubi=)
+ [[https://github.com/cute-jumper/fcitx.el][fcitx]]
+ [[https://github.com/cute-jumper/ace-pinyin][ace-pinyin]]
+ [[https://github.com/coldnew/pangu-spacing][pangu-spacing]]
** Packages
- [[doom-package:][ace-pinyin]]
- [[doom-package:][chinese-wbim]] if [[doom-module:][+wubi]]
- [[doom-package:][fcitx]]
- [[doom-package:][pangu-spacing]]
- [[doom-package:][pyim]] unless [[doom-module:][+wubi]]
** Hacks
+ ~org-html-paragraph~ has been modified to join consecutive Chinese lines into
- ~org-html-paragraph~ has been modified to join consecutive Chinese lines into
a single long line without wanted spaced (when exporting org-mode to html).
* TODO Prerequisites
* TODO Features
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
#+begin_quote
🔨 This module is missing install instructions. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Using fcitx5
Modify ~fcitx-remote-command~ to change the default:
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq fcitx-remote-command "fcitx5-remote")
#+END_SRC
#+end_src
* TODO Troubleshooting
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

79
modules/input/japanese/README.org
View file

@ -1,43 +1,56 @@
#+TITLE: input/japanese
#+DATE: May 13, 2019
#+SINCE: 2.1
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :input japanese
#+subtitle: Ah, a man of culture
#+created: May 13, 2019
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds support for Japanese script.
#+begin_quote
Because I am unable to personally test this module, help to improve this module
would be greatly appreciated! Especially where performance is concerned.
#+end_quote
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
+ [[https://github.com/emacs-jp/migemo][migemo]]
+ [[https://github.com/momomo5717/avy-migemo][avy-migemo]]
+ [[https://github.com/hsaito/ddskk][ddskk]]
+ [[https://github.com/coldnew/pangu-spacing][pangu-spacing]]
** Packages
- [[doom-package:][avy-migemo]]
- [[doom-package:][ddskk]]
- [[doom-package:][migemo]]
- [[doom-package:][pangu-spacing]]
** Hacks
+ ~org-html-paragraph~ has been modified to join consecutive Chinese lines into
- ~org-html-paragraph~ has been modified to join consecutive Chinese lines into
a single long line without wanted spaced (when exporting org-mode to html).
* TODO Prerequisites
+ For incremental search with Migemo, one of the following is required:
+ [[https://github.com/koron/cmigemo][cmigemo]], which is recommended, or
+ [[http://0xcc.net/migemo/][CVS Head Migemo]]
* TODO Features
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
- For incremental search with Migemo, one of the following is required:
- [[https://github.com/koron/cmigemo][cmigemo]] (recommended)
- or [[http://0xcc.net/migemo/][CVS Head Migemo]]
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
* TODO Troubleshooting
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

191
modules/input/layout/README.org
View file

@ -1,140 +1,139 @@
#+TITLE: input/layout
#+DATE: Jun 29, 2020
#+SINCE: v3.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :input layout
#+subtitle: auie,ctsrnm is the superior home row
#+created: Jun 29, 2020
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#bépo][Bépo]]
- [[#easymotion][Easymotion]]
- [[#leaving-mnemonics-alone-when-possible][Leaving mnemonics alone when possible]]
- [[#possible-contributions][Possible contributions]]
- [[#org-mode][Org-mode]]
- [[#configuration][Configuration]]
- [[#bépo-1][Bépo]]
- [[#troubleshooting][Troubleshooting]]
- [[#outstanding-issues-contributions-welcome][Outstanding issues (contributions welcome)]]
- [[#bépo-2][Bépo]]
- [[#how-to-investigate-an-issue-][How to investigate an issue ?]]
- [[#how-to-deactivate-the-new-bindings-and-go-back-to-the-old-ones-][How to deactivate the new bindings and go back to the old ones ?]]
* Description
This module provides barebones support for using Doom with non-qwerty layouts.
* Description :unfold:
This module provides barebones support for using Doom with non-qwerty keyboard
layouts.
** Maintainers
+ @gagbo (Author, Bépo)
- [[doom-user:][@gagbo]] ([[kbd:][+bepo]])
** Module Flags
+ =+azerty= Remaps keybinds to accommodate the
[[https://en.wikipedia.org/wiki/AZERTY][Azerty keyboard layout]].
+ =+bepo= Remaps keybinds to accommodate the
[[https://en.wikipedia.org/wiki/B%C3%89PO][BÉPO keyboard layout]] (version
1.1, in particualr).
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
None
** Module flags
- +azerty ::
Remap keybinds to accommodate the [[https://en.wikipedia.org/wiki/AZERTY][Azerty keyboard layout]].
- +bepo ::
Remap keybinds to accommodate the [[https://en.wikipedia.org/wiki/B%C3%89PO][BÉPO keyboard layout]] (version 1.1, in
particular).
* Prerequisites
If you are using =:editor evil=, you should use =(evil +everywhere)=, as the
module uses =evil-collection= utilities to do the remapping.
** Packages
/This module doesn't install any packages./
If you are not using =:editor evil=, then you have nothing to do.
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
# An in-depth list of features, how to use them, and their dependencies.
** Bépo
Support for the bépo layout includes:
- Setting Avy keys to the correct home row keys
- Changing navigation keys to =ctsr=
+ old =t= is mapped to =j=
+ old =s= is mapped to =k= (i.e. staging in the magit status buffer is done
with =k=)
+ See [[*Configuration][Configuration]] to see where old =c= and =r= functions
- Changing navigation keys to [[kbd:][c]], [[kbd:][t]], [[kbd:][s]], and [[kbd:][r]]
+ old [[kbd:][t]] is mapped to [[kbd:][j]]
+ old [[kbd:][s]] is mapped to [[kbd:][k]] (i.e. staging in the magit status buffer is done with
[[kbd:][k]])
+ See [[*Configuration][Configuration]] to see where old [[kbd:][c]] and [[kbd:][r]] functions
are remapped
- Bind =<>= functions to =«»= keys when possible
- Bind =[]= functions to =()= keys when possible (the "unimpaired-like"
bindings)
- Bind =é= key to =w= functions when possible
- Bind =è= key to useful functions when possible
- Bind =`~= functions to =$#= keys when possible
- Bind [[kbd:][<>]] functions to [[kbd:][«»]] keys when possible
- Bind [[kbd:][[]]] functions to [[kbd:][()]] keys when possible (the "unimpaired-like" bindings)
- Bind [[kbd:][é]] key to [[kbd:][w]] functions when possible
- Bind [[kbd:][è]] key to useful functions when possible
- Bind [[kbd:][`~]] functions to [[kbd:][$#]] keys when possible
*** Easymotion
If you use =evil-easymotion=, then all the bindings that were on =gs= have been
moved to =gé=.
If you use [[doom-package:][evil-easymotion]], then all the bindings that were on [[kbd:][gs]] have been
moved to [[kbd:][gé]].
In short : =g s j= -> =g é t= (evilem-motion-next-line). And so on.
In short : [[kbd:][g s j]] -> [[kbd:][g é t]] (~evilem-motion-next-line~). And so on.
*** Leaving mnemonics alone when possible
Exchanging =hjkl= to =ctsr= has the effect of destroying a few mnemonics: the
change operator becomes =l= for example, or the window split becomes =SPC é k=.
Exchanging [[kbd:][h]]/[[kbd:][j]]/[[kbd:][k]]/[[kbd:][l]] to [[kbd:][c]]/[[kbd:][t]]/[[kbd:][s]]/[[kbd:][r]] has the effect of destroying a few mnemonics: the
change operator becomes [[kbd:][l]] for example, or the window split becomes [[kbd:][SPC é k]].
The module tries to limit those changes to the minimum, especially in special
buffers. A concrete example is magit.
As the =magit: project= buffer (obtained with =magit-status=) does not need
left-right navigation, keys =c=, =r=, =h=, and =l= keep their "expected" bindings,
while =t=, =s=, =j=, and =k= are flipped:
- checking the log from a magit buffer is still on =l=
- staging a file/region has been moved to =k=
As the =magit: project= buffer (obtained with ~M-x magit-status~) does not need
left-right navigation, keys [[kbd:][c]], [[kbd:][r]], [[kbd:][h]], and [[kbd:][l]] keep their "expected" bindings, while
[[kbd:][t]], [[kbd:][s]], [[kbd:][j]], and [[kbd:][k]] are flipped:
- checking the log from a magit buffer is still on [[kbd:][l]]
- staging a file/region has been moved to [[kbd:][k]]
*** Possible contributions
**** Avoid =g= and =z= to be used too often
**** Avoid [[kbd:][g]] and [[kbd:][z]] to be used too often
A nice addition in the future might be to have all the normal mode bindings that
start with =g= start with =,= instead to avoid the curl on these common
bindings. This is *not* implemented for the time being.
start with [[kbd:][g]] start with [[kbd:][,]] instead to avoid the curl on these common bindings.
This is *not* implemented for the time being.
The same thing could be done to =z=, potentially using =à= instead.
The same thing could be done to [[kbd:][z]], potentially using [[kbd:][à]] instead.
**** Proper minor mode
Also, implementing all those changes as a minor we could flip on and off would
help with adoption
**** Put "word" text objects to é instead of w
"inside word" and "around word" are =iw= and =aw=, which use the very poorly
rated =w= key in the bépo layout. Finding a way to use =é= or even =è= more for
these would be a welcome change
"inside word" and "around word" are [[kbd:][iw]] and [[kbd:][aw]], which use the very poorly rated [[kbd:][w]]
key in the bépo layout. Finding a way to use [[kbd:][é]] or even [[kbd:][è]] more for these would be
a welcome change
*** Org-mode
=evil-org= allows to define =evil-org-movement-bindings= to automatically map
movement bindings on non-hjkl keys. It maps automatically keys to =C-c= and
=C-r= in normal and insert states though, and it's not really user friendly in
Emacs to remap those.
[[doom-package:][evil-org]] allows to define ~evil-org-movement-bindings~ to automatically map
movement bindings on non-hjkl keys. It maps automatically keys to [[kbd:][C-c]] and [[kbd:][C-r]] in
normal and insert states though, and it's not really user friendly in Emacs to
remap those.
Therefore, in org-mode:
- =org-shiftright= is bound to =C-»=
- =org-shiftleft= is bound to =C-«=
Therefore, in ~org-mode~:
- ~org-shiftright~ is bound to [[kbd:][C-»]]
- ~org-shiftleft~ is bound to [[kbd:][C-«]]
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Bépo
=+layout-bepo-cr-rotation-style= controls whether:
- =qwerty-c= functions are mapped on =bépo-l= key, and =qwerty-r= functions on
=bépo-h= key (='ergodis=), or
=bépo-h= key (~'ergodis~), or
- =qwerty-c= functions are mapped on =bépo-h= key, and =qwerty-r= functions on
=bépo-l= key (='strict=)
=bépo-l= key (~'strict~)
='strict= would be the logical choice but the =c= functions are used more often
than the =r= ones so [[https://bepo.fr/wiki/Vim#Principe][Ergodis]] advises to actually put all the =c= functions on
the key that does not need a curl.
~'strict~ would be the logical choice but the [[kbd:][c]] functions are used more often
than the [[kbd:][r]] ones so [[https://bepo.fr/wiki/Vim#Principe][Ergodis]] advises to actually put all the [[kbd:][c]] functions on the
key that does not need a curl.
* Troubleshooting
# Common issues and their solution, or places to look for help.
[[doom-report:][Report an issue?]]
** Outstanding issues (contributions welcome)
*** Bépo
- in eshell, the key `c` is still bound to
`evil-collection-eshell-evil-change` in normal mode
- In [[doom-package:][eshell]], the key [[kbd:][c]] is still bound to ~evil-collection-eshell-evil-change~ in
normal mode.
** How to investigate an issue ?
If a key is misbehaving, use =describe-key= (=C-h k= or =SPC h k= or =F1 k=) to
see the functions bound to the key, and more importantly in which map it is
If a key is misbehaving, use ~M-x describe-key~ ([[kbd:][C-h k]] or [[kbd:][SPC h k]] or [[kbd:][F1 k]]) to
see the command bound to the key, and more importantly in which keymap it is
bound.
You should ignore all =evil-collection-...-backup-map= keymaps, as they are
artifacts from =evil-collection-translate-key= and those maps are actually not
You should ignore all ~evil-collection-*-backup-map~ keymaps, as they are
artifacts from ~evil-collection-translate-key~ and those maps are actually not
active.
Most likely the solution is to call one of the "key rotation" functions on the
@ -142,8 +141,16 @@ relevant keymaps.
** How to deactivate the new bindings and go back to the old ones ?
If you are learning a new layout you might want to go back to tho old one to
"get work done". Sadly the only way is to comment out the module, run =doom
sync= and restart emacs.
"get work done". Sadly the only way is to comment out the module, run ~$ doom
sync~ and restart emacs.
Restoring the session =SPC q l= by default helps to lower the impact of the
Restoring the session [[kbd:][SPC q l]] by default helps to lower the impact of the
restart.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

11
modules/lang/README.org Normal file
View file

@ -0,0 +1,11 @@
# -*- mode: doom-docs-org -*-
#+title: :lang
#+created: August 03, 2021
#+since: 21.12.0
* Description
These modules specialize in integration particular languages and their
ecosystems into (Doom) Emacs.
* Frequently asked questions
/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

57
modules/lang/agda/README.org
View file

@ -1,4 +1,57 @@
#+TITLE: :lang agda
# -*- mode: doom-docs-org -*-
#+title: :lang agda
#+subtitle: Types of types of types of types...
#+created: August 21, 2018
#+since: 21.12.0 (#821)
* Description :unfold:
This module adds support for the [[http://wiki.portal.chalmers.se/agda/pmwiki.php][agda]] programming language. The Emacs support
exists directly in the agda repository but not in melpa.
exists directly in the agda repository, but not in melpa.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +local ::
Use the =agda-mode= executable that comes with your local =agda= install.
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
** Packages
- unless [[doom-module:][+local]]
- [[doom-package:][agda-input]]
- [[doom-package:][agda2-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

79
modules/lang/beancount/README.org
View file

@ -1,53 +1,58 @@
#+TITLE: lang/beancount
#+DATE: April 13, 2021
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang beancount
#+subtitle: Mind the GAAP
#+created: April 13, 2021
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds support for [[https://beancount.github.io/][Beancount]] to Emacs. Beancount, like ledger, lets
you [[https://plaintextaccounting.org/][manage your money in plain text]].
+ Supports [[https://github.com/polarmutex/beancount-language-server][beancount-language-server]] (if module is enabled with the =+lsp=
flag).
** Maintainers
This module has no dedicated maintainers.
- @hlissner
** Module Flags
+ =+lsp= Enable support for [beancount-language-server]. Requires Doom's =:tools
lsp= module.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/beancount/beancount-mode][beancount]]
** Module flags
- +lsp ::
Enable LSP support for ~beancount-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/polarmutex/beancount-language-server][beancount-language-server]]).
** Packages
- [[doom-package:][beancount]]
** Hacks
+ Associates the material =attach_money= icon with *.beancount files in the
=all-the-icons= package.
- Associates the material =attach_money= icon with =*.beancount= files in the
[[doom-package:][all-the-icons]] package.
* Prerequisites
This module has no hard prerequisites, but assumes you have [[https://github.com/beancount/beancount][beancount]] installed
in order to generate reports with ~bean-report~.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- [[https://github.com/beancount/beancount][beancount]], for generating reports
- [[https://beancount.github.io/fava/][fava]], for a web interface for your ledgers
* TODO Usage
#+begin_quote
Also: the ~beancount-fava~ command requires [[https://beancount.github.io/fava/][fava]].
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
* TODO Configuration
# How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

261
modules/lang/cc/README.org
View file

@ -1,73 +1,73 @@
#+TITLE: lang/cc
#+DATE: January 16, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang cc
#+subtitle: C > C++ == 1
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#lsp-servers][LSP servers]]
- [[#irony-server][irony-server]]
- [[#macos][macOS]]
- [[#rtags][rtags]]
- [[#configure][Configure]]
- [[#project-compile-settings][Project compile settings]]
- [[#known-issues-with-bear-on-macos][Known issues with bear on macOS]]
- [[#configure-lsp-servers][Configure LSP servers]]
- [[#lsp-mode-with-clangd][LSP-mode with clangd]]
- [[#lsp-mode-with-ccls][LSP-mode with ccls]]
- [[#eglot-with-clangd][Eglot with clangd]]
- [[#eglot-with-ccls][Eglot with ccls]]
- [[#appendix][Appendix]]
- [[#eglot-specific-bindings][Eglot specific bindings]]
* Description
* Description :unfold:
This module adds support for the C-family of languages: C, C++, and Objective-C.
+ Code completion (~company-irony~)
+ eldoc support (~irony-eldoc~)
+ Syntax-checking (~flycheck-irony~)
+ Code navigation (~rtags~)
+ File Templates ([[../../editor/file-templates/templates/c-mode][c-mode]], [[../../editor/file-templates/templates/c++-mode][c++-mode]])
+ Snippets ([[https://github.com/hlissner/doom-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c++-mode][c++-mode]])
+ Several improvements to C++11 indentation and syntax highlighting.
- Code completion (~company-irony~)
- eldoc support (~irony-eldoc~)
- Syntax-checking (~flycheck-irony~)
- Code navigation (~rtags~)
- File Templates ([[../../editor/file-templates/templates/c-mode][c-mode]], [[../../editor/file-templates/templates/c++-mode][c++-mode]])
- Snippets ([[https://github.com/hlissner/doom-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c++-mode][c++-mode]])
- Several improvements to C++11 indentation and syntax highlighting.
** Module Flags
+ ~+lsp~ Disables irony+rtags and replaces them with LSP (ccls by default). This
requires the =:tools lsp= module.
** Maintainers
- [[doom-user:][@hlissner]]
** Plugins
+ [[https://github.com/Kitware/CMake][cmake-mode]]
+ [[https://github.com/chachi/cuda-mode][cuda-mode]]
+ [[https://github.com/liblit/demangle-mode][demangle-mode]]
+ [[https://github.com/jart/disaster][disaster]]
+ [[https://github.com/ludwigpacifici/modern-cpp-font-lock][modern-cpp-font-lock]]
+ [[https://github.com/salmanebah/opencl-mode][opencl-mode]]
+ [[https://github.com/jimhourihan/glsl-mode][glsl-mode]]*
+ [[https://github.com/guidoschmidt/company-glsl][company-glsl]]*
+ =+lsp=
+ [[https://github.com/MaskRay/emacs-ccls][ccls]] if =:tools lsp= has *no* =+eglot= flag
+ =-lsp=
+ [[https://github.com/Sarcasm/irony-mode][irony]]
+ [[https://github.com/ikirill/irony-eldoc][irony-eldoc]]
+ [[https://github.com/Sarcasm/flycheck-irony][flycheck-irony]]
+ [[https://github.com/Sarcasm/company-irony][company-irony]]
+ [[https://github.com/hotpxl/company-irony-c-headers][company-irony-c-headers]]
+ [[https://github.com/Andersbakken/rtags][rtags]]
+ [[https://github.com/Andersbakken/rtags][ivy-rtags]]
+ [[https://github.com/Andersbakken/rtags][helm-rtags]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +lsp ::
Enable LSP support for ~c-mode~, ~c++-mode~, and ~objc-mode~. Requires [[doom-module:][:tools
lsp]] and a langserver (supports ccls, clangd, and cquery). Replaces irony &
rtags.
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
** Packages
- [[doom-package:][cmake-mode]]
- [[doom-package:][company-glsl]]
- [[doom-package:][cuda-mode]]
- [[doom-package:][demangle-mode]]
- [[doom-package:][disaster]]
- [[doom-package:][glsl-mode]]
- [[doom-package:][modern-cpp-font-lock]]
- [[doom-package:][opencl-mode]]
- if [[doom-module:][+lsp]]
- [[doom-package:][ccls]] if [[doom-module:][:tools lsp -eglot]]
- else
- [[doom-package:][company-irony]]
- [[doom-package:][company-irony-c-headers]]
- [[doom-package:][flycheck-irony]]
- [[doom-package:][helm-rtags]] if [[doom-module:][:completion helm]]
- [[doom-package:][irony]]
- [[doom-package:][irony-eldoc]]
- [[doom-package:][ivy-rtags]] if [[doom-module:][:completion ivy]]
- [[doom-package:][rtags]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prerequisites
This module's requirements change depending on how you use it.
+ If =+lsp= is enabled, you need one of *clangd v9+* or *ccls*.
+ If =+lsp= is *not* enabled, you need *irony-server* and *rtags*.
+ Other features in this module depend on:
+ (optional) glslangValidator, for GLSL completion in ~glsl-mode~
+ (optional) cmake, for code completion in ~cmake-mode~
+ You will need a C/C++ compiler, like =gcc= or =clang=.
- If [[doom-module:][+lsp]] is enabled, you need one of *clangd v9+* or *ccls*.
- If [[doom-module:][+lsp]] is *not* enabled, you need *irony-server* and *rtags*.
- Other features in this module depend on:
- (optional) glslangValidator, for GLSL completion in ~glsl-mode~
- (optional) cmake, for code completion in ~cmake-mode~
- You will need a C/C++ compiler, like =gcc= or =clang=.
** LSP servers
=lsp-mode= and =eglot= support a few LSP servers, but =clangd= and =ccls= are
@ -76,13 +76,13 @@ recommended.
+ clangd (must be v9 or newer) :: clangd is included with =llvm= which should be
available through your OS' package manager.
- Linux:
- Debian 11 & Ubuntu 20.10: ~# apt-get install clangd-11~
- Debian 11 & Ubuntu 20.10: ~$ apt-get install clangd-11~
- 20.04 LTS: [[https://pkgs.org/search/?q=clangd][clangd-10]]
- Fedora & CentOS/RHEL 8+: ~# dnf install clang-tools-extra~
- openSUSE: ~# zypper install clang~
- Arch: ~# pacman -S clang~
- Fedora & CentOS/RHEL 8+: ~$ dnf install clang-tools-extra~
- openSUSE: ~$ zypper install clang~
- Arch: ~$ pacman -S clang~
- BSDs:
- NetBSD & OpenBSD: ~# pkg_add clang-tools-extra~
- NetBSD & OpenBSD: ~$ pkg_add clang-tools-extra~
- macOS: ~$ brew install llvm~ // 1GB+ installation! May take a while!
- Windows: use the win64 installer from [[https://releases.llvm.org/download.html][LLVM's GitHub release page]].
+ ccls :: Available in many OS' package managers as =ccls=. Otherwise, there are
@ -97,14 +97,13 @@ irony-install-server~ in Emacs.
*** macOS
Due to linking issues, macOS users must compile irony-server manually:
#+BEGIN_SRC sh
#+begin_src sh
brew install cmake
brew install llvm
git clone https://github.com/Sarcasm/irony-mode irony-mode
#+END_SRC
#+end_src
#+BEGIN_SRC bash
#+begin_src sh
mkdir irony-mode/server/build
pushd irony-mode/server/build
@ -121,7 +120,7 @@ install_name_tool -change @rpath/libclang.dylib \
# Cleanup
popd
rm -rf irony-mode
#+END_SRC
#+end_src
** rtags
Code navigation requires an [[https://github.com/Andersbakken/rtags][rtags]] server (~rdm~) installed. This should be
@ -130,12 +129,36 @@ available through your OS's package manager.
This module will auto-start ~rdm~ when you open C/C++ buffers (so long as one
isn't already running). If you prefer to run it yourself:
#+BEGIN_SRC sh
#+begin_src sh
rdm &
rc -J $PROJECT_ROOT # loads PROJECT_ROOT's compile_commands.json
#+END_SRC
#+end_src
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
1. Enable this module.
2. Enable the ~+lsp~ flag for the appropriate modules you want LSP support for
(e.g. ~:lang (python +lsp)~ or ~:lang (rust +lsp)~),
3. Install the prerequisite LSP servers through your package manager or other
means. You can find a list of supported servers on [[https://github.com/emacs-lsp/lsp-mode#supported-languages][the lsp-mode project page]].
4. Run ~$ doom sync~ on the command line and restart Emacs.
** Eglot-specific bindings
When using [[doom-module:][+lsp]] and [[doom-module:][:tools lsp +eglot]], [[doom-package:][lsp-mode]] is replaced with [[doom-package:][eglot]], and an
additional function to get inheritance type hierarchy is added:
| Binding | Description |
|----------------------------+------------------------------------------------|
| [[kbd:][<localleader> c t]] | Display inheritance type hierarchy (upwards) |
| [[kbd:][<prefix> <localleader> c t]] | Display inheritance type hierarchy (downwards) |
* TODO Configure
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configure
** Project compile settings
By default, a set of default compile settings are defined in
~+cc-default-compiler-options~ for C, C++ and Objective C. Irony, rtags and
@ -145,16 +168,16 @@ For a more universal solution: both LSP servers and irony will recognize a
[[https://sarcasm.github.io/notes/dev/compilation-database.html#ninja][compilation database]] (a ~compile_commands.json~ file). There are [[https://sarcasm.github.io/notes/dev/compilation-database.html][many ways to
generate one]]. Here is an example using [[http://www.cmake.org/][CMake]] and [[https://github.com/rizsotto/Bear][bear]]:
#+BEGIN_SRC sh
#+begin_src sh
# For CMake projects
cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON .
#+END_SRC
#+end_src
#+BEGIN_SRC sh
#+begin_src sh
# For non-CMake projects
make clean
bear make
#+END_SRC
#+end_src
Use ~M-x +cc/reload-compile-db~ to reload your compile db in an already-open
C/C++/ObjC buffer.
@ -164,7 +187,6 @@ MacOS' [[https://support.apple.com/en-us/HT204899][System Integrity Protection (
under ~/usr/bin/~ which results in an empty compilation database.
From the bear [[https://github.com/rizsotto/Bear#empty-compilation-database-on-os-x-captain-or-fedora][readme]]:
#+begin_quote
Security extension/modes on different operating systems might disable library
preloads. This case Bear behaves normally, but the result compilation database
@ -182,77 +204,76 @@ such tool might be scan-build. The build system shall respect CC and CXX
environment variables.
#+end_quote
A workaround might be to install ~make~ via Homebrew which puts ~gmake~
under ~/usr/local/~.
#+BEGIN_SRC sh
A workaround might be to install ~make~ via Homebrew which puts ~gmake~ under
=/usr/local/=:
#+begin_src sh
brew install make
#+END_SRC
#+BEGIN_SRC sh
#+end_src
#+begin_src sh
make clean
bear gmake
#+END_SRC
#+end_src
Additional info:
+ [[https://github.com/rizsotto/Bear/issues/158][Empty compilation database with compiler in /usr/local]]
+ [[https://github.com/rizsotto/Bear/issues/152][Workaround for 'Empty compilation database on OS X Captain]]
- [[https://github.com/rizsotto/Bear/issues/158][Empty compilation database with compiler in /usr/local]]
- [[https://github.com/rizsotto/Bear/issues/152][Workaround for 'Empty compilation database on OS X Captain]]
** Configure LSP servers
Search for your combination of =(LSP client package, LSP server)=. You are using
=LSP-mode= by default, =eglot= if you have =:tools (lsp +eglot)= active in your
=init.el= file.
[[doom-package:][lsp-mode]] by default, [[doom-package:][eglot]] if you have [[doom-module:][:tools lsp +eglot]] active in
=$DOOMDIR/init.el= file.
*** LSP-mode with clangd
#+begin_src emacs-lisp
(after! lsp-clangd
(setq lsp-clients-clangd-args
'("-j=3"
"--background-index"
"--clang-tidy"
"--completion-style=detailed"
"--header-insertion=never"
"--header-insertion-decorators=0"))
(set-lsp-priority! 'clangd 2))
#+end_src
#+BEGIN_SRC elisp
(setq lsp-clients-clangd-args '("-j=3"
"--background-index"
"--clang-tidy"
"--completion-style=detailed"
"--header-insertion=never"
"--header-insertion-decorators=0"))
(after! lsp-clangd (set-lsp-priority! 'clangd 2))
#+END_SRC
This will both set your clangd flags and choose =clangd= as the default LSP server everywhere clangd can be used.
This will both set your clangd flags and choose =clangd= as the default LSP
server everywhere clangd can be used.
*** LSP-mode with ccls
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(after! ccls
(setq ccls-initialization-options '(:index (:comments 2) :completion (:detailedLabel t)))
(set-lsp-priority! 'ccls 2)) ; optional as ccls is the default in Doom
#+END_SRC
#+end_src
This will both set your ccls flags and choose ccls as the default server. [[https://github.com/MaskRay/ccls/wiki/Customization#--initjson][CCLS
documentation]] lists available options, use =t= for ~true~, =:json-false= for
~false~, and =:json-null= for ~null~.
*** Eglot with clangd
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(set-eglot-client! 'cc-mode '("clangd" "-j=3" "--clang-tidy"))
#+END_SRC
#+end_src
This will both set your clangd flags and choose clangd as the default server (if
it is the last =set-eglot-client! 'cc-mode= in your config).
*** Eglot with ccls
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(set-eglot-client! 'cc-mode '("ccls" "--init={\"index\": {\"threads\": 3}}"))
#+END_SRC
#+end_src
This will both set your ccls flags and choose ccls as the default server (if it
is the last =set-eglot-client! 'cc-mode= in your config). [[https://github.com/MaskRay/ccls/wiki/Customization#--initjson][CCLS documentation]]
lists available options
* Appendix
** Eglot specific bindings
When using =+lsp= and =:tools (lsp +eglot)=, lsp-mode is replaced with eglot,
and an additional function to get inheritance type hierarchy is added
| Binding | Description |
|------------------------------+--------------------------------------------------|
| ~<localleader> c t~ | ~Display inheritance type hierarchy (upwards)~ |
| ~<prefix> <localleader> c t~ | ~Display inheritance type hierarchy (downwards)~ |
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

198
modules/lang/clojure/README.org
View file

@ -1,115 +1,121 @@
#+TITLE: lang/clojure
#+DATE: May 30, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang clojure
#+subtitle: Java with a lisp
#+created: May 30, 2017
#+since: 2.0.3
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#keybindings][Keybindings]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds support for the Clojure(Script) language.
+ Interactive development environment (~cider~): REPL, compilation, debugging,
- Interactive development environment (~cider~): REPL, compilation, debugging,
running tests, definitions & documentation lookup, code completion, and much
more
+ Refactoring (~clj-refactor~)
+ Linting (~clj-kondo~), requires ~:checkers syntax~
+ LSP support (~clojure-lsp~)
- Refactoring (~clj-refactor~)
- Linting (~clj-kondo~), requires ~:checkers syntax~
- LSP support (~clojure-lsp~)
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+lsp= Enables LSP support, alongside Cider.
** Module flags
- +lsp ::
Enable LSP support for ~clojure-mode~ (alongside Cider). Requires [[doom-module:][:tools lsp]]
and a langserver (supports [[https://clojure-lsp.io/][clojure-lsp]]).
** Plugins
+ [[https://github.com/clojure-emacs/cider][cider]]
+ [[https://github.com/clojure-emacs/clj-refactor.el][clj-refactor]]
+ [[https://github.com/borkdude/flycheck-clj-kondo][flycheck-clj-kondo]]
** Packages
- [[doom-package:][cider]]
- [[doom-package:][clj-refactor]]
- [[doom-package:][flycheck-clj-kondo]] if [[doom-module:][:checkers syntax]]
** Hacks
+ Error messages emitted from CIDER are piped into the REPL buffer when it is
- Error messages emitted from CIDER are piped into the REPL buffer when it is
first opened, to make them easier to notice.
+ Disabled the help banner when opening the cider REPL.
- Disabled the help banner when opening the cider REPL.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prerequisites
This module requires:
- [[https://clojure.org/][clojure]]
- [[https://leiningen.org/][leiningen]], for the REPL
- [[https://github.com/borkdude/clj-kondo][clj-kondo]], for linting code
- [[https://clojure-lsp.github.io/clojure-lsp/][clojure-lsp]], for LSP support (if [[doom-module:][+lsp]])
+ [[https://clojure.org/][clojure]]
+ [[https://leiningen.org/][leiningen]] (REPL)
+ [[https://github.com/borkdude/clj-kondo][clj-kondo]] (linter)
+ With =+lsp=
+ [[https://clojure-lsp.github.io/clojure-lsp/][clojure-lsp]]
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
** Keybindings
| Binding | Description |
|---------------------+------------------------------------------------------|
| =<localleader> '​= | =cider-jack-in-clj= |
| =<localleader> C= | =cider-connect-cljs= |
| =<localleader> M= | =cider-macroexpand-all= |
| =<localleader> R= | =hydra-cljr-help-menu/body= |
| =<localleader> c= | =cider-connect-clj= |
| =<localleader> e D= | =cider-insert-defun-in-repl= |
| =<localleader> e E= | =cider-insert-last-sexp-in-repl= |
| =<localleader> e R= | =cider-insert-region-in-repl= |
| =<localleader> e b= | =cider-eval-buffer= |
| =<localleader> e d= | =cider-eval-defun-at-point= |
| =<localleader> e e= | =cider-eval-last-sexp= |
| =<localleader> e r= | =cider-eval-region= |
| =<localleader> e u= | =cider-undef= |
| =<localleader> g b= | =cider-pop-back= |
| =<localleader> g g= | =cider-find-var= |
| =<localleader> g n= | =cider-find-ns= |
| =<localleader> h a= | =cider-apropos= |
| =<localleader> h c= | =cider-clojuredocs= |
| =<localleader> h d= | =cider-doc= |
| =<localleader> h j= | =cider-javadoc= |
| =<localleader> h n= | =cider-find-ns= |
| =<localleader> h w= | =cider-clojuredocs-web= |
| =<localleader> i e= | =cider-enlighten-mode= |
| =<localleader> i i= | =cider-inspect= |
| =<localleader> i r= | =cider-inspect-last-result= |
| =<localleader> m "​= | =cider-jack-in-cljs= |
| =<localleader> m= | =cider-macroexpand-1= |
| =<localleader> n N= | =cider-browse-ns-all= |
| =<localleader> n n= | =cider-browse-ns= |
| =<localleader> n r= | =cider-ns-refresh= |
| =<localleader> p d= | =cider-pprint-eval-defun-at-point= |
| =<localleader> p D= | =cider-pprint-eval-defun-to-comment= |
| =<localleader> p p= | =cider-pprint-eval-last-sexp= |
| =<localleader> p P= | =cider-pprint-eval-last-sexp-to-comment= |
| =<localleader> p r= | =cider-pprint-eval-last-sexp-to-repl= |
| =<localleader> r B= | =+clojure/cider-switch-to-repl-buffer-and-switch-ns= |
| =<localleader> r L= | =cider-load-buffer-and-switch-to-repl-buffer= |
| =<localleader> r R= | =cider-restart= |
| =<localleader> r b= | =cider-switch-to-repl-buffer= |
| =<localleader> r c= | =cider-find-and-clear-repl-output= |
| =<localleader> r l= | =cider-load-buffer= |
| =<localleader> r n= | =cider-repl-set-ns= |
| =<localleader> r q= | =cider-quit= |
| =<localleader> r r= | =cider-ns-refresh= |
| =<localleader> t a= | =cider-test-rerun-test= |
| =<localleader> t l= | =cider-test-run-loaded-tests= |
| =<localleader> t n= | =cider-test-run-ns-tests= |
| =<localleader> t p= | =cider-test-run-project-tests= |
| =<localleader> t r= | =cider-test-rerun-failed-tests= |
| =<localleader> t s= | =cider-test-run-ns-tests-with-filters= |
| =<localleader> t t= | =cider-test-run-test= |
| Keybind | Command |
|-------------------+------------------------------------------------------|
| [[kbd:][<localleader> ']] | ~cider-jack-in-clj~ |
| [[kbd:][<localleader> C]] | ~cider-connect-cljs~ |
| [[kbd:][<localleader> M]] | ~cider-macroexpand-all~ |
| [[kbd:][<localleader> R]] | ~hydra-cljr-help-menu/body~ |
| [[kbd:][<localleader> c]] | ~cider-connect-clj~ |
| [[kbd:][<localleader> e D]] | ~cider-insert-defun-in-repl~ |
| [[kbd:][<localleader> e E]] | ~cider-insert-last-sexp-in-repl~ |
| [[kbd:][<localleader> e R]] | ~cider-insert-region-in-repl~ |
| [[kbd:][<localleader> e b]] | ~cider-eval-buffer~ |
| [[kbd:][<localleader> e d]] | ~cider-eval-defun-at-point~ |
| [[kbd:][<localleader> e e]] | ~cider-eval-last-sexp~ |
| [[kbd:][<localleader> e r]] | ~cider-eval-region~ |
| [[kbd:][<localleader> e u]] | ~cider-undef~ |
| [[kbd:][<localleader> g b]] | ~cider-pop-back~ |
| [[kbd:][<localleader> g g]] | ~cider-find-var~ |
| [[kbd:][<localleader> g n]] | ~cider-find-ns~ |
| [[kbd:][<localleader> h a]] | ~cider-apropos~ |
| [[kbd:][<localleader> h c]] | ~cider-clojuredocs~ |
| [[kbd:][<localleader> h d]] | ~cider-doc~ |
| [[kbd:][<localleader> h j]] | ~cider-javadoc~ |
| [[kbd:][<localleader> h n]] | ~cider-find-ns~ |
| [[kbd:][<localleader> h w]] | ~cider-clojuredocs-web~ |
| [[kbd:][<localleader> i e]] | ~cider-enlighten-mode~ |
| [[kbd:][<localleader> i i]] | ~cider-inspect~ |
| [[kbd:][<localleader> i r]] | ~cider-inspect-last-result~ |
| [[kbd:][<localleader> m "]] | ~cider-jack-in-cljs~ |
| [[kbd:][<localleader> m]] | ~cider-macroexpand-1~ |
| [[kbd:][<localleader> n N]] | ~cider-browse-ns-all~ |
| [[kbd:][<localleader> n n]] | ~cider-browse-ns~ |
| [[kbd:][<localleader> n r]] | ~cider-ns-refresh~ |
| [[kbd:][<localleader> p d]] | ~cider-pprint-eval-defun-at-point~ |
| [[kbd:][<localleader> p D]] | ~cider-pprint-eval-defun-to-comment~ |
| [[kbd:][<localleader> p p]] | ~cider-pprint-eval-last-sexp~ |
| [[kbd:][<localleader> p P]] | ~cider-pprint-eval-last-sexp-to-comment~ |
| [[kbd:][<localleader> p r]] | ~cider-pprint-eval-last-sexp-to-repl~ |
| [[kbd:][<localleader> r B]] | ~+clojure/cider-switch-to-repl-buffer-and-switch-ns~ |
| [[kbd:][<localleader> r L]] | ~cider-load-buffer-and-switch-to-repl-buffer~ |
| [[kbd:][<localleader> r R]] | ~cider-restart~ |
| [[kbd:][<localleader> r b]] | ~cider-switch-to-repl-buffer~ |
| [[kbd:][<localleader> r c]] | ~cider-find-and-clear-repl-output~ |
| [[kbd:][<localleader> r l]] | ~cider-load-buffer~ |
| [[kbd:][<localleader> r n]] | ~cider-repl-set-ns~ |
| [[kbd:][<localleader> r q]] | ~cider-quit~ |
| [[kbd:][<localleader> r r]] | ~cider-ns-refresh~ |
| [[kbd:][<localleader> t a]] | ~cider-test-rerun-test~ |
| [[kbd:][<localleader> t l]] | ~cider-test-run-loaded-tests~ |
| [[kbd:][<localleader> t n]] | ~cider-test-run-ns-tests~ |
| [[kbd:][<localleader> t p]] | ~cider-test-run-project-tests~ |
| [[kbd:][<localleader> t r]] | ~cider-test-rerun-failed-tests~ |
| [[kbd:][<localleader> t s]] | ~cider-test-run-ns-tests-with-filters~ |
| [[kbd:][<localleader> t t]] | ~cider-test-run-test~ |
* TODO Configuration
# How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

81
modules/lang/common-lisp/README.org
View file

@ -1,22 +1,11 @@
#+TITLE: lang/common-lisp
#+DATE: June 13, 2018
#+SINCE: v2.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang common-lisp
#+subtitle: If you've seen one lisp, you've seen them all
#+created: June 13, 2018
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#sly][Sly]]
- [[#org-mode][org-mode]]
- [[#configuration][Configuration]]
* Description
This module provides support for [[https://lisp-lang.org/][Common Lisp]] and the [[https://github.com/joaotavora/sly][Sly]] development
* Description :unfold:
This module provides support for [[https://lisp-lang.org/][Common Lisp]] and the [[doom-package:][Sly]] development
environment. Common Lisp is not a single language but a specification, with many
competing compiler implementations. By default, [[http://www.sbcl.org/][Steel Bank Common Lisp]] (SBCL) is
assumed to be installed, but this can be configured.
@ -27,45 +16,65 @@ style often unseen in other languages. Compiled Common Lisp programs are trusted
to run unmodified for a long time.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
This module has no dedicated maintainers.
** Module flags
/This module has no flags./
** Module Flags
** Packages
- [[doom-package:][sly]]
- [[doom-package:][sly-macrostep]]
- [[doom-package:][sly-repl-ansi-color]]
This module provides no flags.
** Hacks
/No hacks documented for this module./
** Plugins
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
+ [[https://github.com/joaotavora/sly][sly]]
+ [[https://github.com/joaotavora/sly-macrostep][sly-macrostep]]
+ [[https://github.com/PuercoPop/sly-repl-ansi-color][sly-repl-ansi-color]]
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prerequisites
This module requires [[http://www.sbcl.org/][SBCL]].
This module requires the [[http://www.sbcl.org/][SBCL]] compiler to be installed.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
This module does not integrate with the =lsp= module. Sly (and SLIME before it) is
This module does not integrate with [[doom-module:][:tools lsp]]. Sly (and SLIME before it) is
considered the defacto development environment for Common Lisp and provides much
of what is normally expected of an LSP, plus tight integration with the REPL and
Emacs.
** Sly
Using this module is mostly a matter of using Sly. Please consider reading
through [[http://joaotavora.github.io/sly/#A-SLY-tour-for-SLIME-users][the Sly Tour]].
A Sly session will be started when you open a =.lisp= file. Use =SPC m '= to switch
to the REPL minibuffer.
A Sly session will be started when you open a =.lisp= file. Use [[kbd:][<localleader> ']]
to switch to the REPL minibuffer.
** org-mode
This module also enables the evaluation of =lisp= source blocks in Org Mode.
However, you will need a running Sly session for this to work. =M-x sly= starts
However, you will need a running Sly session for this to work. ~M-x sly~ starts
such a session if you didn't have one open already.
* Configuration
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
If you don't want Sly to use SBCL, you can configure the variable
~inferior-lisp-program~ to some other binary on your PATH.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

54
modules/lang/coq/README.org
View file

@ -1,6 +1,54 @@
#+TITLE: :lang coq
# -*- mode: doom-docs-org -*-
#+title: :lang coq
#+subtitle: Proofs as programs
#+created: August 14, 2018
#+since: 21.12.0 (#804)
* Description :unfold:
This module adds [[https://coq.inria.fr][coq]] support, powered by [[https://proofgeneral.github.io][Proof General]].
+ Code completion ([[https://github.com/cpitclaudel/company-coq][company-coq]])
+ [[https://github.com/hlissner/doom-snippets/tree/master/coq-mode][Snippets]]
- Code completion ([[https://github.com/cpitclaudel/company-coq][company-coq]])
- [[https://github.com/hlissner/doom-snippets/tree/master/coq-mode][Snippets]]
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][proof-general]]
- [[doom-package:][company-coq]]
** Hacks
+ Replaces coq-mode abbrevs with yasnippet snippets from doom's snippet library
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
+ [[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
+ To use the completion features of company-coq you need to enable ~(:completion company)~
+ Make sure you have Coq installed and that the ~coqtop~ command is available. This comes with a standard installation of Coq.
You can use your linux distribution's Coq package or one of the methods given on the [[https://coq.inria.fr/download][Coq website]].
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Configuration
This module provides no additional configuration over that of the [[Packages]] it loads
* Troubleshooting
See [[https://github.com/hlissner/doom-emacs/issues?q=is%3Aissue+is%3Aopen+label%3A%22%3Alang+coq"][related github issues]]
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

98
modules/lang/crystal/README.org
View file

@ -1,62 +1,66 @@
#+TITLE: lang/crystal
#+DATE: January 16, 2017
#+SINCE: v1.3
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang crystal
#+subtitle: Ruby at the speed of C
#+created: January 16, 2017
#+since: 1.3
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#crystal][Crystal]]
- [[#macos][MacOS]]
- [[#arch][Arch]]
- [[#icr-repl][ICR (REPL)]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This modules adds [[https://crystal-lang.org/][crystal]] support.
+ Syntax-checking (~flycheck~)
+ REPL (~inf-crystal~)
- Syntax-checking (~flycheck~)
- REPL (~inf-crystal~)
** Maintainers
This module has no dedicated maintainers.
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
+ [[https://github.com/crystal-lang-tools/emacs-crystal-mode/][crystal-mode]]
+ [[https://github.com/brantou/inf-crystal.el/][inf-crystal]]
+ if ~:checkers syntax~ is enabled
- [[https://github.com/crystal-lang-tools/emacs-crystal-mode/][flycheck-crystal]]
- [[https://github.com/crystal-ameba/ameba.el/][flycheck-ameba]]
** Packages
- [[doom-package:][crystal-mode]]
- [[doom-package:][inf-crystal]]
- if [[doom-module:][:checkers syntax]]
- [[doom-package:][flycheck-ameba]]
- [[doom-package:][flycheck-crystal]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- [[https://crystal-lang.org/install/][The crystal compiler]]
- [[https://github.com/crystal-community/icr][ICR]], for the REPL
* Prerequisites
** Crystal
you need to install [[https://crystal-lang.org/install/][the crystal compiler]].
*** MacOS
#+begin_src shell
brew install crystal
#+end_src
*** Arch
#+begin_src shell
sudo pacman -S crystal shards
#+end_src
- MacOS: ~$ brew install crystal~
- Arch Linux: ~$ pacman -S crystal shards~
** ICR (REPL)
you need to install [[https://github.com/crystal-community/icr][ICR]].
[[https://github.com/crystal-community/icr#installation][Installation instructions]].
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
* TODO Configuration
# How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

101
modules/lang/csharp/README.org
View file

@ -1,43 +1,78 @@
#+TITLE: :lang csharp
# -*- mode: doom-docs-org -*-
#+title: :lang csharp
#+subtitle: Unity, .NET, and Mono shenanigans
#+created: February 20, 2017
#+since: 2.0.0
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#macos][MacOS]]
- [[#arch-linux][Arch Linux]]
- [[#nixos][NixOS]]
* Description
This module adds C# support to Emacs. Powered by omnisharp (directly or through
* Description :unfold:
This module adds C# support to Emacs, powered by Omnisharp (directly or through
LSP).
** Module Flags
+ =+lsp= Enables omnisharp through LSP support (requires omnisharp).
+ =+unity= Enables special support for the [[https://unity.com/][Unity game engine]] (particularly,
support for HLSL shaders).
+ =+dotnet= Enables Dotnet transient interface with Sharper
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/josteink/csharp-mode][csharp-mode]]
+ [[https://github.com/omajid/csproj-mode][csproj-mode]]
+ [[https://github.com/OmniSharp/omnisharp-emacs][omnisharp]]* (not =+lsp=)
+ [[https://github.com/midnightSuyama/shader-mode][shader-mode]]* (=+unity=)
+ [[https://github.com/sebasmonia/sharper][sharper]] (=+dotnet=)
** Module flags
- +dotnet ::
Enable Dotnet transient interface with Sharper
- +lsp ::
Enable LSP support for ~csharp-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports =omnisharp-roslyn=).
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
- +unity ::
Enable special support for the [[https://unity.com/][Unity game engine]] (particularly, support for
HLSL shaders).
** Packages
- [[doom-package:][csharp-mode]]
- [[doom-package:][csproj-mode]]
- [[doom-package:][shader-mode]] if [[doom-module:][+unity]]
- [[doom-package:][sharper]] if [[doom-module:][+dotnet]]
- [[doom-package:][sln-mode]]
* Prerequisites
This module needs:
** Hacks
/No hacks documented for this module./
+ omnisharp (with the ~+lsp~ flag, this must be installed externally. Without
it, use ~M-x omnisharp-install-server~)
+ .NET SDKs (on Windows)
+ Mono (on UNIX platforms)
+ .NET Core 1.X - 3.X or .NET 5 for cross platform
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- Mono (on UNIX platforms)
- .NET SDKs (on Windows)
- .NET Core 1.X - 3.X or .NET 5 for cross platform
- omnisharp-rosyln (if [[doom-module:][+lsp]])
** TODO MacOS
** Arch Linux
#+BEGIN_SRC sh
sudo pacman --needed --noconfirm -S mono
#+END_SRC
#+begin_src sh
pacman --needed --noconfirm -S mono
#+end_src
** TODO NixOS
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

151
modules/lang/dart/README.org
View file

@ -1,47 +1,47 @@
#+TITLE: lang/dart
#+DATE: February 16, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang dart
#+subtitle: Paint ui and not much else
#+created: February 15, 2020
#+since: 21.12.0 (#2729)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#installing-dart-sdk][Installing Dart SDK]]
- [[#installing-flutter-sdk][Installing Flutter SDK]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#dart--flutter][Dart & Flutter]]
- [[#android][Android]]
- [[#flutter-mobile-development-on-desktop][Flutter mobile development on desktop]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
[[https://dart.dev/][Dart]] is a client-optimized language by Google for fast apps on any platform. It
is fast and optimized for UI, famous for the [[https://flutter.io/][Flutter]] framework, also made by
Google. Both Flutter and Dart are free and open-source.
* Description
[[https://dart.dev/][Dart]] is a client-optimized language by Google for fast apps on any platform.
It is fast and optimized for UI, famous for the [[https://flutter.io/][Flutter]] framework, also
made by Google. Both Flutter and Dart are free and open-source.
This module wraps ~dart-mode~, with [[https://microsoft.github.io/language-server-protocol/][LSP]] features like code completion for =.dart= files,
syntax highlighting, debugging, closing labels, etc.
This module wraps ~dart-mode~, with [[https://microsoft.github.io/language-server-protocol/][LSP]] features like code completion for
=.dart= files, syntax highlighting, debugging, closing labels, etc.
** Maintainers
+ [[https://github.com/ericdallo][@ericdallo]]
- [[doom-user:][@ericdallo]]
** Module Flags
+ =+lsp= Enable LSP server integration.
+ =+flutter= Adds ~flutter~ integration and some sane defaults for Flutter
development along with ~hover~ for desktop development.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/bradyt/dart-mode][dart-mode]]
+ [[https://github.com/amake/flutter.el][flutter.el]]
+ [[https://github.com/ericdallo/hover.el][hover.el]]
** Module flags
- +flutter ::
Enable ~flutter~ integration and some sane defaults for Flutter development
along with ~hover~ for desktop development.
- +lsp ::
Enable LSP support for ~dart-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports flutter).
* Prerequisites
Make sure that the Dart SDK is on your ~PATH~, and if using Flutter, make sure
the Flutter binary is on your ~PATH~ as well.
** Packages
- [[doom-package:][dart-mode]]
- [[doom-package:][flutter.el]]
- [[doom-package:][hover.el]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
Make sure that the Dart SDK is on your =$PATH=, and if using Flutter, make sure
the Flutter binary is on your =$PATH= as well.
** Installing Dart SDK
Before starting note that Flutter SDK will have a version of Dart. Therefore,
@ -52,23 +52,23 @@ The stable version of the SDK is in most major distributions repositories.
If you find it necessary to install any other version or build from source,
please refer to the official website at: https://dart.dev/get-dart
+ *On Debian (also Ubuntu and its derivations):*
#+BEGIN_SRC shell
sudo apt-get install dart
#+END_SRC
+ *On Arch Linux (and derivations like Manjaro):*
#+BEGIN_SRC shell
sudo pacman -S dart
#+END_SRC
+ *On macOS*:
#+BEGIN_SRC shell
- *On Debian (also Ubuntu and its derivations):*
#+begin_src sh
apt-get install dart
#+end_src
- *On Arch Linux (and derivations like Manjaro):*
#+begin_src sh
pacman -S dart
#+end_src
- *On macOS*:
#+begin_src sh
brew tap dart-lang/dart
brew install dart
#+END_SRC
+ *On NixOS*:
#+BEGIN_SRC shell
#+end_src
- *On NixOS*:
#+begin_src sh
nix-env -iA nixpkgs.dart
#+END_SRC
#+end_src
** Installing Flutter SDK
Due to complications with permissions, it is suggested not to use AUR or any
@ -77,22 +77,30 @@ automatic installation tools for Flutter SDK.
On any system just run the following commands to install Flutter, once you have
met dependencies named on [[https://flutter.dev/docs/get-started/install/][the site]]:
#+BEGIN_SRC shell
#+begin_src sh
git clone https://github.com/flutter/flutter --branch stable # to download Flutter
export PATH="$PATH:$(pwd)/flutter/bin" # to add it to PATH
flutter doctor # for Dependency check and further instructions
#+END_SRC
#+end_src
* Features
+ Syntax highlighting and formatting for ~.dart~ files provided by LSP
+ Auto import
+ Widget guide lines for Flutter
+ Closing labels for constructors
+ Run tests interactively
+ Outline support via ~lsp-treemacs~
+ Emacs functions for running and debugging Flutter projects
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
- Syntax highlighting and formatting for ~.dart~ files provided by LSP.
- Auto import.
- Widget guide lines for Flutter.
- Closing labels for constructors.
- Run tests interactively.
- Outline support via [[doom-package:][lsp-treemacs]].
- Emacs functions for running and debugging Flutter projects.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Dart & Flutter
On Linux, the installers for Dart and Flutter use the ~/opt~ directory, and this
module assumes that. However, you may set ~lsp-dart-sdk-dir~ to your Dart
@ -101,18 +109,31 @@ LSP can find the language server included with the Dart SDK.
Alternatively, these variables shouldn't be necessary if you just include Dart
and Flutter on your ~PATH~ variable.
** Android
You will also need to setup your system for Android development if you intend to
use Flutter to develop mobile applications. Refer to your distributions package
manager for details. In most distributions the ~/opt/android-sdk~ directory is
used, and you might have to change some permissions in this directory since it's
owned by root. The [[https://wiki.archlinux.org/index.php/Android][Arch Linux wiki has a great guide on this here.]]
** Flutter mobile development on desktop
[[https://github.com/go-flutter-desktop/go-flutter][Hover]] is an application that can run Flutter mobile apps on your desktop, this
makes the mobile development a lot easier without the need to setup an Android emulator.
makes the mobile development a lot easier without the need to setup an Android
emulator.
* Troubleshooting
[[doom-report:][Report an issue?]]
See the configuration section for information on the binaries for Dart and
Flutter. On new installs to the ~/opt~ directory, you will likely need to edit
the permissions of the ~/opt/dart-sdk~ and ~/opt/flutter~ directories (not to
Flutter. On new installs to the =/opt= directory, you will likely need to edit
the permissions of the =/opt/dart-sdk= and =/opt/flutter= directories (not to
mention the Android SDK, as discussed above).
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

50
modules/lang/data/README.org Normal file
View file

@ -0,0 +1,50 @@
# -*- mode: doom-docs-org -*-
#+title: :lang data
#+subtitle: A dumping ground for data formats
#+created: February 20, 2017
#+since: 2.0.0
* Description :unfold:
This module adds Emacs support for CSV and XML files.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][csv-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

54
modules/lang/dhall/README.org Normal file
View file

@ -0,0 +1,54 @@
# -*- mode: doom-docs-org -*-
#+title: :lang dhall
#+subtitle: Config as code
#+created: August 03, 2021
#+since: 21.12.0
* Description :unfold:
This module adds [[https://dhall-lang.org/][Dhall]] language support to Emacs.
Dhall is a programmable configuration language that you can think of as: JSON +
functions + types + imports.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][dhall-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires the =dhall-json= package, which provides both the
=dhall-to-json=, =dhall-to-yaml=, and =dhall-format= executables.
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

149
modules/lang/elixir/README.org
View file

@ -1,79 +1,106 @@
#+TITLE: lang/elixir
#+DATE: June 24, 2019
#+SINCE: v2.0.9
# -*- mode: doom-docs-org -*-
#+title: :lang elixir
#+subtitle: Erlang done right
#+created: May 24, 2017
#+since: 2.0.3 (#83)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#install-elixir][Install Elixir]]
- [[#with-asdf][With ~asdf~]]
- [[#arch-linux][Arch Linux]]
- [[#gentoo-linux][Gentoo Linux]]
- [[#opensuse][openSUSE]]
- [[#features][Features]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
* Description :unfold:
This module provides support for [[https://elixir-lang.org/][Elixir programming language]] via [[doom-package:][alchemist]] or
[[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]].
* Description
This module provides support for [[https://elixir-lang.org/][Elixir programming language]] via [[https://github.com/tonini/alchemist.el][alchemist.el]]
or [[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]].
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
+ ~+lsp~ Enable LSP support. Requires [[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]].
- +lsp ::
Enable LSP support for ~elixir-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]]).
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
** Plugins
+ [[https://github.com/elixir-editors/emacs-elixir][elixir-mode]]
+ [[https://github.com/tonini/alchemist.el][alchemist.el]]
+ [[https://github.com/aaronjensen/flycheck-credo][flycheck-credo]]
+ [[https://github.com/ananthakumaran/exunit.el][exunit]]
** Packages
- [[doom-package:][alchemist]]
- [[doom-package:][elixir-mode]]
- [[doom-package:][exunit]]
- [[doom-package:][flycheck-credo]] if [[doom-module:][:checkers syntax]]
* Prerequisites
You should have Elixir installed, for example, via your distribution's package
manager or a version management tool such as [[https://github.com/asdf-vm/asdf-elixir][asdf]].
** Hacks
/No hacks documented for this module./
If you want to add support for LSP ([[modules/tools/lsp][:tools lsp]]), be sure to install [[https://github.com/JakeBecker/elixir-ls/][elixir-ls]]
and enable ~:tools lsp~ in your ~init.el~.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires Elixir. Install it via your distribution's package manager
or a version management tool such as [[https://github.com/asdf-vm/asdf-elixir][asdf]].
To add LSP support, install [[https://github.com/JakeBecker/elixir-ls/][elixir-ls]] and enable [[doom-module:][:tools lsp]].
To support linting with [[https://github.com/rrrene/credo][credo]], add ~:checkers syntax~ to ~$DOOMDIR/init.el~.
To support linting with [[https://github.com/rrrene/credo][credo]], add ~:checkers syntax~ to your ~init.el~
** Install Elixir
(See [[https://elixir-lang.org/install.html]] for other operating systems)
*** With ~asdf~
#+BEGIN_SRC sh
#+begin_src sh
asdf plugin-add elixir
asdf install elixir 1.9.1
#+END_SRC
#+end_src
*** Arch Linux
#+BEGIN_SRC sh :dir /sudo::
sudo pacman -S elixir
#+END_SRC
#+begin_src sh
pacman -S elixir
#+end_src
*** Gentoo Linux
#+BEGIN_SRC sh :dir /sudo::
sudo emerge -v dev-lang/elixir
#+END_SRC
#+begin_src sh
emerge -v dev-lang/elixir
#+end_src
*** openSUSE
#+BEGIN_SRC sh :dir /sudo::
sudo zypper install elixir
#+END_SRC
See [[https://elixir-lang.org/install.html]] for other operating systems
* Features
- Code completion (~:completion company~)
- Documentation lookup (~:tools lookup~)
#+begin_src sh
zypper install elixir
#+end_src
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
- Code completion ([[doom-module:][:completion company]])
- Documentation lookup ([[doom-module:][:tools lookup]])
- Mix integration
- Phoenix support
- ~iex~ integration (~:tools eval~)
- Syntax checking (~:checkers syntax~, using [[https://github.com/aaronjensen/flycheck-credo][flycheck-credo]]~)
* Appendix
** Commands
*** exunit-mode
The exunit-mode prefix is =SPC m t=. Here is some examples:
| | | |
| command | key / ex command | description |
|------------------------------------------+------------------+--------------------------------------------------------|
| ~exunit-verify-all~ | =SPC m t a= | Runs exunit on all files |
| ~exunit-rerun~ | =SPC m t r= | Re-runs last exunit command |
| ~exunit-verify~ | =SPC m t v= | Runs exunit on current file |
| ~exunit-verify-single~ | =SPC m t s= | Runs exunit for the item on cursor |
| ~exunit-toggle-file-and-test~ | =SPC m t t= | Switch between implementation and test |
| ~exunit-toggle-file-and-test-other-window~ | =SPC m t T= | Switch between implementation and test in other window |
- ~iex~ integration ([[doom-module:][:tools eval]])
- Syntax checking ([[doom-module:][:checkers syntax]], using [[doom-package:][flycheck-credo]])
** exunit-mode
The exunit-mode prefix is [[kbd:][<localleader> t]]. Here is some examples:
| command | key / ex command | description |
|--------------------------------------------+-------------------+--------------------------------------------------------|
| ~exunit-verify-all~ | [[kbd:][<localleader> t a]] | Runs exunit on all files |
| ~exunit-rerun~ | [[kbd:][<localleader> t r]] | Re-runs last exunit command |
| ~exunit-verify~ | [[kbd:][<localleader> t v]] | Runs exunit on current file |
| ~exunit-verify-single~ | [[kbd:][<localleader> t s]] | Runs exunit for the item on cursor |
| ~exunit-toggle-file-and-test~ | [[kbd:][<localleader> t t]] | Switch between implementation and test |
| ~exunit-toggle-file-and-test-other-window~ | [[kbd:][<localleader> t T]] | Switch between implementation and test in other window |
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

61
modules/lang/elm/README.org Normal file
View file

@ -0,0 +1,61 @@
# -*- mode: doom-docs-org -*-
#+title: :lang elm
#+subtitle: Care for a cup of TEA?
#+created: May 21, 2017
#+since: 2.0.3 (#74)
* Description :unfold:
This module adds [[https://elm-lang.org/][Elm]] support to Doom Emacs.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +lsp ::
Enable LSP support for ~elm-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/elm-tooling/elm-language-server][elm-language-server]]).
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
** Packages
- [[doom-package:][elm-mode]]
- [[doom-package:][flycheck-elm]] if [[doom-module:][:checkers syntax]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
#+begin_quote
🔨 /This module's prerequisites are not all documented./ [[doom-contrib-module:][Document them?]]
#+end_quote
- If [[doom-module:][+lsp]] is enabled, [[https://github.com/elm-tooling/elm-language-server][elm-language-server]] is required to be installed and in
your =$PATH=.
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

94
modules/lang/emacs-lisp/README.org
View file

@ -1,60 +1,74 @@
#+TITLE: lang/emacs-lisp
#+DATE: January 16, 2017
#+SINCE: v1.3
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang emacs-lisp
#+subtitle: A parsel-tongue for the oldest serpent
#+created: January 16, 2017
#+since: 1.3
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module extends support for Emacs Lisp in Doom Emacs.
+ Macro expansion
+ Go-to-definitions or references functionality
- Macro expansion
- Go-to-definitions or references functionality
- Syntax highlighting for defined and quoted symbols
- Replaces the built-in help with the more powerful [[doom-package:][helpful]]
- Adds function example uses to documentation
** Maintainers
+ @hlissner (author)
- [[doom-user:][@hlissner]]
** Module Flags
This module provides no flags.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/jorgenschaefer/emacs-buttercup][buttercup]]
+ [[https://github.com/Wilfred/elisp-def][elisp-def]]
+ [[https://github.com/xuchunyang/elisp-demos][elisp-demos]]
+ [[https://github.com/flycheck/flycheck-cask][flycheck-cask]] (=:checkers syntax=)
+ [[https://github.com/Fanael/highlight-quoted][highlight-quoted]]
+ [[https://github.com/joddie/macrostep][macrostep]]
+ [[https://github.com/tonini/overseer.el][overseer]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][buttercup]]
- [[doom-package:][elisp-def]]
- [[doom-package:][elisp-demos]]
- [[doom-package:][flycheck-cask]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][flycheck-package]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][highlight-quoted]]
- [[doom-package:][macrostep]]
- [[doom-package:][overseer]]
** Hacks
+ Symbols that are defined in the current session are highlighted with
- Symbols that are defined in the current session are highlighted with
~font-lock-variable-face~.
+ Eldoc will display the values of variables next to its documentation.
+ ~elisp-demos~ was modified to display API demos for Doom's standard library
- Eldoc will display the values of variables next to its documentation.
- ~elisp-demos~ was modified to display API demos for Doom's standard library
(in [[file:../../../docs/api.org][docs/api.org]]).
+ This module extends imenu support for Doom's API (e.g. ~package!~,
- This module extends imenu support for Doom's API (e.g. ~package!~,
~use-package~, ~after!~)
+ Flycheck has been configured to tone down the false positives when you are
- Flycheck has been configured to tone down the false positives when you are
editing your Emacs or Doom config.
* Prerequisites
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module's sole dependency is Emacs. It's very obscure, you wouldn't know
about it.
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
# How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

2
modules/lang/emacs-lisp/autoload.el
View file

@ -95,7 +95,7 @@ if it's callable, `apropos' otherwise."
(with-demoted-errors "%s"
(re-search-forward
(if (caddr module)
"\\* Module Flags$"
"\\* Module flags$"
"\\* Description$"))
(when (caddr module)
(re-search-forward (format "=\\%s=" (caddr module))

4
modules/lang/emacs-lisp/demos.org
View file

@ -1,5 +1,5 @@
#+TITLE: API Demos
#+PROPERTY: header-args:emacs-lisp :results verbatim
#+title: API Demos
#+property: header-args:elisp :results pp
This file contains demos of Doom's public API; its core library, macros, and
autodefs. It is used by the =elisp-demos= package to display examples of their

78
modules/lang/erlang/README.org
View file

@ -1,39 +1,61 @@
#+TITLE: lang/erlang
#+DATE: January 14, 2020
#+SINCE: {replace with next tagged release version}
#+STARTUP: inlineimages nofold
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
* Description
# -*- mode: doom-docs-org -*-
#+title: :lang erlang
#+subtitle: an elegant language for a more civilized age
#+created: April 07, 2018
#+since: 21.12.0 (#497)
* Description :unfold:
This module provides support [[https://www.erlang.org/][Erlang programming language]]. Support for the
[[https://github.com/erlang/sourcer][sourcer]] language server is optional.
Includes:
- Code completion ([[doom-module:][+lsp]], [[doom-module:][:completion company]], & [[doom-module:][:completion ivy]])
- Syntax checking ([[doom-module:][:checkers syntax]])
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ ~+lsp~ Enable LSP Support. Requires [[https://github.com/erlang/sourcer][sourcer]].
** Module flags
- +lsp ::
Enable LSP support for ~erlang-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/erlang/sourcer][sourcer]]).
** Packages
- [[doom-package:][flycheck-rebar3]]
- [[doom-package:][ivy-erlang-complete]]
** Plugins
+ Erlang Mode (bundled with Erlang installations)
+ [[https://github.com/joedevivo/flycheck-rebar3][flycheck-rebar3]]
+ [[https://github.com/s-kostyaev/ivy-erlang-complete][ivy-erlang-complete]]
** Hacks
/No hacks documented for this module./
* Prerequisites
You should have Erlang installed. Check your distribution's package manager or a
version management tool such as [[https://github.com/kerl/kerl][kerl]].
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
If you want LSP support, install [[https://github.com/erlang/sourcer][sourcer]].
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Features
- Code completion (~+lsp~, ~:completion company~, and ~:completion ivy~)
- Syntax checking (~:checkers syntax~)
This module requires Erlang be installed (which includes ~erlang-mode~). Check
your distribution's package manager or a version management tool such as [[https://github.com/kerl/kerl][kerl]].
For LSP support, install [[https://github.com/erlang/sourcer][sourcer]].
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

76
modules/lang/ess/README.org
View file

@ -1,34 +1,66 @@
#+TITLE: :lang ess
# -*- mode: doom-docs-org -*-
#+title: :lang ess
#+subtitle: 73.6% of all statistics are made up
#+created: February 05, 2018
#+since: 21.12.0 (#410)
* Description :unfold:
This module adds support for various statistics languages, including R, S-Plus,
SAS, Julia and Stata.
* Table of Contents :TOC:
- [[#prequisites][Prequisites]]
- [[#appendix][Appendix]]
- [[#keybindings][Keybindings]]
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +stan ::
Enable support for ~stan-mode~, including code completion and syntax checking.
** Packages
- [[doom-package:][ess]]
- [[doom-package:][ess-R-data-view]]
- [[doom-package:][polymode]]
- [[doom-package:][poly-R]]
- if [[doom-module:][+stan]]
- [[doom-package:][company-stan]] if [[doom-module:][:completion company]]
- [[doom-package:][eldoc-stan]]
- [[doom-package:][flycheck-stan]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][stan-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prequisites
This module has several optional dependencies:
+ [[https://github.com/jimhester/lintr][lintr]]: Enables R linting.
+ [[https://github.com/REditorSupport/languageserver][languageserver]]: Enables LSP support in an R buffer (with =+lsp= flag).
* Appendix
** Keybindings
*** :map ess-doc-map
- [[https://github.com/jimhester/lintr][lintr]]: for R linting.
- [[https://github.com/REditorSupport/languageserver][languageserver]]: for LSP support in an R buffer (with [[doom-module:][+lsp]] flag).
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** :map ess-doc-map
| key | command |
|-----+----------------------------|
| "h" | ess-display-help-on-object |
| "p" | ess-R-dv-pprint |
| "t" | ess-R-dv-ctable |
*** :map ess-mode-map
** :map ess-mode-map
| key | command |
|--------------+-----------------------|
| "<s-return>" | ess-eval-line |
| "<up>" | comint-next-input |
| "<down>" | comint-previous-input |
**** :localleader
** :localleader
| state | key | command |
|-------+-------------+---------------------------------------------------|
| :nv | "," | ess-eval-region-or-function-or-paragraph-and-step |
@ -55,3 +87,19 @@ This module has several optional dependencies:
| :n | "cm" | ess-noweb-mark-chunk |
| :n | "cp" | ess-noweb-previous-chunk |
| :n | "cn" | ess-noweb-next-chunk |
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

75
modules/lang/factor/README.org
View file

@ -1,43 +1,58 @@
#+TITLE: lang/factor
#+DATE: December 3, 2019
#+SINCE: v3.0.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang factor
#+subtitle: ...
#+created: December 03, 2019
#+since: 21.12.0 (#2129)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds support to the [[https://github.com/factor/factor][factor]] programming language and its associated
_fuel_ emacs plugin.
[[doom-package:][fuel]] emacs plugin.
+ If possible, include a brief list of feature highlights here
+ Like code completion, syntax checking or available snippets
+ Include links to packages & external things where possible
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
{A list of linked plugins}
** Packages
/This module doesn't install any packages./
** Hacks
{A list of internal modifications to included packages}
/No hacks documented for this module./
* Prerequisites
You must install [[https://github.com/factor/factor][factor]] to use the advanced functionality of this module.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires [[https://github.com/factor/factor][factor]] for its advanced functionality.
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
This module requires the installation of factor to be available at
=fuel-factor-root-dir=. Here's an example of how to set it:
#+BEGIN_SRC emacs-lisp
~fuel-factor-root-dir~. E.g.
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq fuel-factor-root-dir "/Applications/factor")
#+END_SRC
#+end_src
* Troubleshooting
Common issues and their solution, or places to look for help.
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

100
modules/lang/faust/README.org
View file

@ -1,46 +1,70 @@
#+TITLE: lang/faust
#+DATE: July 23, 2019
#+SINCE: v2.1.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang faust
#+subtitle: DSP, but you can keep your soul
#+created: October 14, 2019
#+since: 21.12.0 (#1898)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#plugins][Plugins]]
- [[#features][Features]]
* Description :unfold:
Add support to [[https://faust.grame.fr/][Faust language]] inside emacs.
* Description
Add support to Faust language inside emacs.
- Faust code syntax highlighting and indentation
- Project-based (inter-linked Faust files)
- Build/compile with output window
- Graphic diagrams generation and visualization in the (default) browser
- Browse generated C++ code inside Emacs
- Inter-linked files/buffers :
- From "component" to Faust file
- From "include" to Faust library file
- From error to file:line number
- From function name to online documentation
- Fully configurable (build type/target/architecture/toolkit, keyboard
shortcuts, etc.)
- Automatic keyword completion (if Auto-Complete is installed)
- Automatic objets (functions, operators, etc.) template insertion with default
sensible values (if [[doom-module:][:editor snippets]] is enabled)
- Modeline indicator of the state of the code
+ Faust code syntax hightlighting and indentation
+ Project-based (inter-linked Faust files)
+ Build/compile with output window
+ Graphic diagrams generation and vizualisation in the (default) browser
+ Browse generated C++ code inside Emacs
+ Inter-linked files/buffers :
+ From "component" to Faust file
+ From "include" to Faust library file
+ From error to file:line number
+ From function name to online documentation
+ Fully configurable (build type/target/architecture/toolkit, keyboard shortcuts, etc.)
+ Automatic keyword completion (if Auto-Complete is installed)
+ Automatic objets (functions, operators, etc.) template insertion with default sensible values (if Yasnippet is installed)
+ Modeline indicator of the state of the code
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://bitbucket.org/yphil/faustine][faustine]]
** Packages
- [[doom-package:][faustine]]
* Features
Keybindings
** Hacks
- Both ~faust-mode~ and ~faustine-mode~ are hardcoded to use [[doom-package:][auto-complete]],
which Doom does not use. Its obnoxious 'You really should install and use
auto-complete' warnings have been silenced.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
| Binding | Description |
|-------------------+----------------------|
| ~<localleader> b~ | ~build~ |
| ~<localleader> c~ | ~syntax check~ |
| ~<localleader> d~ | ~diagram~ |
| ~<localleader> h~ | ~online dock~ |
| ~<localleader> RET~ | ~mdoc~ |
| ~<localleader> o~ | ~toggle output buffer~ |
| ~<localleader> s~ | ~source code~ |
| ~<localleader> r~ | ~run~ |
| ~<localleader> S-b~ | ~build all~ |
| ~<localleader> S-d~ | ~diagram all~ |
| [[kbd:][<localleader> b]] | build |
| [[kbd:][<localleader> c]] | syntax check |
| [[kbd:][<localleader> d]] | diagram |
| [[kbd:][<localleader> h]] | online dock |
| [[kbd:][<localleader> RET]] | mdoc |
| [[kbd:][<localleader> o]] | toggle output buffer |
| [[kbd:][<localleader> s]] | source code |
| [[kbd:][<localleader> r]] | run |
| [[kbd:][<localleader> S-b]] | build all |
| [[kbd:][<localleader> S-d]] | diagram all |
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

101
modules/lang/fsharp/README.org
View file

@ -1,58 +1,71 @@
#+TITLE: lang/fsharp
#+DATE: May 22, 2019
#+SINCE: {replace with next tagged release version}
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang fsharp
#+subtitle: ML stands for Microsoft's Language
#+created: May 23, 2019
#+since: 21.12.0 (#1327)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#mono][Mono]]
- [[#osx][OSX]]
- [[#arch-linux][Arch Linux]]
- [[#lsp][LSP]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module adds [[https://fsharp.org/][F#]] support to Doom Emacs.
* Description
# A summary of what this module does.
*Includes:*
- Code completion
- eldoc support
- Syntax checking
# + If possible, include a brief list of feature highlights here
# + Like code completion, syntax checking or available snippets
# + Include links to packages & external things where possible
This module adds [[https://fsharp.org/][F#]] support.
+ Code completion
+ eldoc support
+ Syntax checking
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +lsp ::
Enable LSP support for ~fsharp-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-fsharp.el][lsp-fsharp]].).
** Packages
- [[doom-package:][fsharp-mode]]
- [[doom-package:][lsp-fsharp]] if [[doom-package:][+lsp]]
** Module Flags
+ =+lsp= Enables lsp-fsharp (this requires ~:tools lsp~ to be enabled).
** Plugins
+ [[https://github.com/fsharp/emacs-fsharp-mode][fsharp-mode]]
+ =+lsp=
+ [[https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-fsharp.el][lsp-fsharp]]
** Hacks
None so far.
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
To get code completion/syntax checking when not using lsp, you will need to
install [[https://www.mono-project.com/][mono]].
* Prerequisites
** Mono
To get code completion/syntax checking when not using lsp, you will need to install [[https://www.mono-project.com/][mono]].
*** OSX
Do *NOT* install mono via brew. See this [[https://github.com/fsharp/FsAutoComplete/issues/331][issue]].
*Do NOT install mono via brew.* See this [[https://github.com/fsharp/FsAutoComplete/issues/331][issue]].
*** Arch Linux
#+BEGIN_SRC sh
sudo pacman -S mono
#+END_SRC
#+begin_src sh
pacman -S mono
#+end_src
** LSP
The language server is automatically installed by [[https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-fsharp.el][lsp-fsharp]].
* Features
An in-depth list of features, how to use them, and their dependencies.
* Configuration
How to configure this module, including common problems and how to address them.
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
Common issues and their solution, or places to look for help.
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

100
modules/lang/fstar/README.org
View file

@ -1,56 +1,74 @@
#+TITLE: lang/fstar
#+DATE: February 2, 2020
#+SINCE: 2.0.10
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang fstar
#+subtitle: (Dependent) types and (monadic) effects and Z3
#+created: February 02, 2020
#+since: 21.12.0 (#2473)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#f][F*]]
- [[#macos][macOS]]
- [[#arch-linux][Arch Linux]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds [[https://fstar-lang.org/][F*]] support, powered by [[https://github.com/FStarLang/fstar-mode.el][fstar-mode.el]].
+ Syntax highlighting
+ Interactively process F* files one definition at a time
+ Query the running F* process to look up definitions, documentation, and
- Syntax highlighting
- Interactively process F* files one definition at a time
- Query the running F* process to look up definitions, documentation, and
theorems
** Maintainers
+ [[https://github.com/tchajed][@tchajed]] (Author)
- [[doom-user:][@tchajed]]
** Module Flags
This module provides no flags.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/FStarLang/fstar-mode.el][fstar-mode]]
** Module flags
/This module has no flags./
* Prerequisites
** F*
While fstar-mode supports the latest release of F*, you may have a better
experience installing a more recent version from source. See F*'s [[https://github.com/FStarLang/FStar/blob/master/INSTALL.md][INSTALL.md]].
*** macOS
#+BEGIN_SRC sh
** Packages
- [[doom-package:][fstar-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires [[https://github.com/FStarLang/FStar/blob/master/INSTALL.md][F*]].
While ~fstar-mode~ supports the latest release of F*, you may have a better
experience installing a more recent version from source.
** macOS
#+begin_src sh
brew install fstar
#+END_SRC
*** Arch Linux
Install ~fstar~ from the AUR:
#+BEGIN_SRC sh
#+end_src
** Arch Linux
~fstar~ is available in the AUR:
#+begin_src sh
yaourt -S fstar
#+END_SRC
#+end_src
* Features
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Configuration
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
If you're having trouble getting F* to start correctly, you may need to
configure a few variables in fstar-mode; see its [[https://github.com/FStarLang/fstar-mode.el][README]] for more details.
[[doom-report:][Report an issue?]]
- If you're having trouble getting F* to start correctly, you may need to
configure a few variables in ~fstar-mode~; see its [[https://github.com/FStarLang/fstar-mode.el][README]] for more details.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

94
modules/lang/gdscript/README.org
View file

@ -1,55 +1,79 @@
#+TITLE: lang/gdscript
#+DATE: May 27, 2020
#+SINCE: v2.0.9
# -*- mode: doom-docs-org -*-
#+title: :lang gdscript
#+subtitle: the language you waited for
#+created: June 01, 2020
#+since: 21.12.0 (#3239)
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
* Description
* Description :unfold:
This module adds support for GDScript, the scripting language of the [[http://godotengine.org/][Godot]] game
engine, to Doom Emacs, powered by [[https://github.com/GDQuest/emacs-gdscript-mode][gdscript-mode]].
** Module Flags
+ =+lsp= Enables LSP support for gdscript-mode. This requires the =:tools lsp=
module to be enabled and you need to open your project in Godot ~3.2.1~ or
above to run the language server.
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
This module provides no plugins.
** Module flags
- +lsp ::
Enable LSP support for ~gdscript-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(Godot ~3.2.1~ or newer).
* Prerequisites
To format your GDScript code, you need to install [[https://github.com/Scony/godot-gdscript-toolkit/][gdtoolkit]]:
** Packages
- [[doom-package:][gdscript-mode]]
#+BEGIN_SRC shell
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires Godot 3.2.1+ to be installed to make use of any of its
features (beyond syntax highlighting).
To format your GDScript code, you will need [[https://github.com/Scony/godot-gdscript-toolkit/][gdtoolkit]]:
#+begin_src sh
# On Windows
pip install gdtoolkit
# On MacOS and Linux
pip3 install gdtoolkit
#+END_SRC
#+end_src
* Features
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** LSP support
The language server support for GDScript is built into by lsp-mode. As long as
you have the ~lsp~ module installed, you should be able to use the language
server.
you have [[doom-module:][+lsp]] and [[doom-module:][:tools lsp]] enabled, and Godot 3.2.1+ installed, it should work
out of the box.
Godot's language server is built into the game engine, so you need to open your
project in Godot ~3.2.1~ or above for the GDScript language server to be
available.
/Note that the GDScript language server has known issues causing some errors
with lsp-mode. They should be addressed in future releases./
* Configuration
This module provides no configuration.
* Appendix
** Commands
Press ~SPC m~ (local leader key) to explore available commands.
Press the localleader key ([[kbd:][SPC m]] for evil users, [[kbd:][C-c l]] otherwise) to explore
available commands.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
[[doom-report:][Report an issue?]]
- The GDScript language server has known issues causing some errors with
[[doom-package:][lsp-mode]]. They should be addressed in future releases.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

154
modules/lang/go/README.org
View file

@ -1,81 +1,76 @@
#+TITLE: lang/go
#+DATE: January 16, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang go
#+subtitle: The hipster dialect
#+created: June 15, 2015
#+since: 0.7
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#go][Go]]
- [[#dependencies][Dependencies]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module adds [[https://golang.org][Go]] support, with optional (but recommended) LSP support via
[[https://github.com/golang/tools/blob/master/gopls/README.md][gopls]].
+ Code completion (~gocode~)
+ Documentation lookup (~godoc~)
+ Eldoc support (~go-eldoc~)
+ REPL (~gore~)
+ Syntax-checking (~flycheck~)
+ Auto-formatting on save (~gofmt~) (requires =:editor (format +onsave)=)
+ Code navigation & refactoring (~go-guru~)
+ [[../../editor/file-templates/templates/go-mode][File templates]]
+ [[https://github.com/hlissner/doom-snippets/tree/master/go-mode][Snippets]]
+ Generate testing code (~go-gen-test~)
+ Code checking (~flycheck-golangci-lint~)
- Code completion (~gocode~)
- Documentation lookup (~godoc~)
- Eldoc support (~go-eldoc~)
- REPL (~gore~)
- Syntax-checking (~flycheck~)
- Auto-formatting on save (~gofmt~) (requires [[doom-module:][:editor format +onsave]])
- Code navigation & refactoring (~go-guru~)
- [[../../editor/file-templates/templates/go-mode][File templates]]
- [[https://github.com/hlissner/doom-snippets/tree/master/go-mode][Snippets]]
- Generate testing code (~go-gen-test~)
- Code checking (~flycheck-golangci-lint~)
** Module Flags
+ =+lsp= Enables integration for the gopls LSP server. It is highly recommended
you use this, as the non-LSP experience is deprecated (and poor).
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/dominikh/go-mode.el][go-mode]]
+ [[https://github.com/syohex/emacs-go-eldoc][go-eldoc]]
+ [[https://github.com/dominikh/go-mode.el][go-guru]]
+ [[https://github.com/manute/gorepl-mode][gorepl-mode]]
+ [[https://github.com/brantou/emacs-go-tag][go-tag]]
+ [[https://github.com/mdempsky/gocode][company-go]]* =DEPRECATED=
+ [[https://github.com/s-kostyaev/go-gen-test][go-gen-test]]
+ [[https://github.com/weijiangan/flycheck-golangci-lint][flycheck-golangci-lint]] (if =:checkers syntax= is enabled)
** Module flags
- +lsp ::
Enable LSP support for ~go-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports gopls). Highly recommended, as the non-LSP experience is deprecated
(and poor).
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
** Packages
- [[doom-package:][company-go]] if [[doom-module:][:completion company]] (DEPRECATED)
- [[doom-package:][flycheck-golangci-lint]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][go-eldoc]]
- [[doom-package:][go-gen-test]]
- [[doom-package:][go-guru]]
- [[doom-package:][go-mode]]
- [[doom-package:][gorepl-mode]]
- [[doom-package:][go-tag]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires Go, a valid =$GOPATH=, and a number of go packages, listed
below.
* Prerequisites
** Go
To get started with Go, you need the ~go~ tool:
*** MacOS
#+BEGIN_SRC bash
brew install go
#+END_SRC
*** Arch Linux
#+BEGIN_SRC bash
sudo pacman -S go
#+END_SRC
*** openSUSE
#+BEGIN_SRC sh :dir /sudo::
sudo zypper install go
#+END_SRC
- macOS: ~$ brew install go~
- Arch Linux: ~$ pacman -S go~
- openSUSE: ~$ zypper install go~
** Dependencies
This module requires a valid ~GOPATH~, and the following Go packages:
- ~gocode~ (for code completion & eldoc support)
- ~godoc~ (for documentation lookup)
- ~gorename~ (for extra refactoring commands)
- ~gore~ (for the REPL)
- ~guru~ (for code navigation & refactoring commands)
- ~goimports~ (/optional/: for auto-formatting code on save & fixing imports)
- ~gotests~ (for generate test code)
- ~gomodifytags~ (for manipulating tags)
+ ~gocode~ (for code completion & eldoc support)
+ ~godoc~ (for documentation lookup)
+ ~gorename~ (for extra refactoring commands)
+ ~gore~ (for the REPL)
+ ~guru~ (for code navigation & refactoring commands)
+ ~goimports~ (optional: for auto-formatting code on save & fixing imports)
+ ~gotests~ (for generate test code)
+ ~gomodifytags~ (for manipulating tags)
#+BEGIN_SRC sh
#+begin_src sh
export GOPATH=~/work/go
go install github.com/x-motemen/gore/cmd/gore@latest
@ -86,14 +81,29 @@ go install golang.org/x/tools/cmd/gorename@latest
go install golang.org/x/tools/cmd/guru@latest
go install github.com/cweill/gotests/gotests@latest
go install github.com/fatih/gomodifytags@latest
#+END_SRC
#+end_src
+ ~golangci-lint~ (optional: for flycheck to integrate golangci-lint results)
it is recommended to *not* use ~go get~ to install this one, check the
- ~golangci-lint~ (optional: for flycheck to integrate golangci-lint results) it
is recommended to *not* use ~$ go get~ to install this one, check the
[[https://github.com/golangci/golangci-lint#binary-release][documentation]].
* TODO Features
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

96
modules/lang/haskell/README.org
View file

@ -1,43 +1,42 @@
#+TITLE: lang/haskell
#+DATE: January 16, 2017
#+SINCE: v0.7
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang haskell
#+subtitle: A language that's lazier than I am
#+created: March 29, 2016
#+since: 0.9
* Table of Contents :TOC:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
* Description
Adds Haskell support to Doom Emacs.
* Description :unfold:
This module adds Haskell support to Doom Emacs.
** Maintainers
This module has no dedicated maintainers.
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+lsp= Enable LSP support with for [[https://github.com/haskell/haskell-language-server][haskell-language-server]] (requires the =:tools lsp= module).
** Module flags
- +lsp ::
Enable LSP support for ~haskell-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/haskell/haskell-language-server][haskell-language-server]]).
** Plugins
+ [[https://github.com/haskell/haskell-mode][haskell-mode]]
+ [[https://github.com/emacs-lsp/lsp-haskell][lsp-haskell]] (=+lsp=, =:tools lsp=)
** Packages
- [[doom-package:][haskell-mode]]
- [[doom-package:][lsp-haskell]] if [[doom-module:][+lsp]]
** Hacks
/No hacks documented for this module./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
* Prerequisites
It is recommended to install the haskell tooling using [[https://www.haskell.org/ghcup/][ghcup]]. Only ghc is needed
for basic functionality:
#+BEGIN_SRC bash
#+begin_src sh
ghcup install ghc
#+END_SRC
#+end_src
but =+lsp= users should also install the language server:
#+BEGIN_SRC bash
#+begin_src sh
ghcup install hls
#+END_SRC
#+end_src
Installing [[https://www.haskell.org/cabal/][cabal]] or [[https://docs.haskellstack.org/en/stable/README/][stack]] as well is recommended, and can be done through
=ghcup=.
@ -49,25 +48,44 @@ system package manager, cabal, or stack.
formatters such as [[https://github.com/lspitzner/brittany][brittany]], [[https://github.com/ennocramer/floskell][floskell]], [[https://github.com/tweag/ormolu][ormolu]], [[https://github.com/fourmolu/fourmolu][fourmolu]], and [[https://github.com/haskell/stylish-haskell][stylish-haskell]],
which can be installed through system package manager, cabal, or stack.
* Features
This module intergrates the haskell packages into Doom by providing things such
as repl support, project root recognition, etc. It also provide the following
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
This module integrates the haskell packages into Doom by providing things such
as REPL support, project root recognition, etc. It also provide the following
keybindings:
| Keybinding | Description |
|-------------------+-----------------------------------------------|
| =<localleader> b= | Build the current cabal project |
| =<localleader> c= | Visit the =.cabal= file of the current buffer |
| =<localleader> h= | Toggle visibility of the form at point |
| =<localleader> H= | hides all top level functions |
| Keybinding | Description |
|-----------------+-----------------------------------------------|
| [[kbd:][<localleader> b]] | Build the current cabal project |
| [[kbd:][<localleader> c]] | Visit the =.cabal= file of the current buffer |
| [[kbd:][<localleader> h]] | Toggle visibility of the form at point |
| [[kbd:][<localleader> H]] | hides all top level functions |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
After installing your preferred formatter, make sure to set
=lsp-haskell-formatting-provider= to it.
Make sure to configure the lsp to use your perfered formatter, e.g.:
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
;; ~/.doom.d/config.el
(after!
(after! lsp-haskell
(setq lsp-haskell-formatting-provider "brittany"))
#+END_SRC
#+end_src
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

50
modules/lang/hy/README.org Normal file
View file

@ -0,0 +1,50 @@
# -*- mode: doom-docs-org -*-
#+title: :lang hy
#+subtitle: Lisp is better than ugly
#+created: June 25, 2017
#+since: 2.0.4 (#122)
* Description :unfold:
/(No description yet)/
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][hy-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires [[https://docs.hylang.org/en/alpha/][Hy]].
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

71
modules/lang/idris/README.org
View file

@ -1,30 +1,55 @@
#+TITLE: lang/idris
#+DATE: October 6, 2020
#+SINCE: v2.0.9
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang idris
#+subtitle: A language you can depend on
#+created: August 21, 2018
#+since: 21.12.0 (#822)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
* Description :unfold:
This module adds rudimentary [[https://www.idris-lang.org/][Idris]] support to Doom Emacs.
* Description
This module adds rudimentary Idris support.
** Maintainers
This module has no dedicated maintainers.
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
This module provides no flags.
** Module flags
/This module has no flags./
** Plugins
# A list of linked plugins
+ [[https://github.com/idris-hackers/idris-mode/][idris-mode]]
** Packages
- [[doom-package:][idris-mode]]
* Prerequisites
This module has no prerequisites.
** Hacks
/No hacks documented for this module./
* Features
In addition to =idris-mode= goodness, adds frequently used functions under the localleader key.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
#+begin_quote
🔨 /No installation steps have been documented./ [[doom-contrib-module:][Document them?]]
#+end_quote
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
In addition to ~idris-mode~ goodness, adds frequently used functions under the
[[kbd:][<localleader>]] key.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

233
modules/lang/java/README.org
View file

@ -1,148 +1,171 @@
#+TITLE: lang/java
#+DATE: January 16, 2017
#+SINCE: v1.3
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang java
#+subtitle: The poster child for carpal tunnel syndrome
#+created: January 16, 2017
#+since: 1.3
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#prerequisites][Prerequisites]]
- [[#openjdk-11][OpenJDK 11]]
- [[#ubuntu][Ubuntu]]
- [[#fedora][Fedora]]
- [[#oracle-jdk-11][Oracle JDK 11]]
- [[#ubuntu-1][Ubuntu]]
- [[#fedora-1][Fedora]]
- [[#multiple-java-versions][Multiple Java Versions]]
- [[#features][Features]]
- [[#lsp-features][=+lsp= features]]
- [[#meghanada-features][=+meghanada= features]]
- [[#configuration][Configuration]]
- [[#lsp][=+lsp=]]
* Description :unfold:
This module adds [[https://www.java.com][Java]] support to Doom Emacs, including ~android-mode~ and
~groovy-mode~.
* Description
This module adds [[https://www.java.com][java]] support to Doom Emacs, including =android-mode= and
=groovy-mode=.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+lsp= Enables integration for the eclipse.jdt.ls LSP server.
+ =+meghanada= Enables the [[https://github.com/mopemope/meghanada-emacs/tree/master][meghanada-mode]]
** Module flags
- +lsp ::
Enable LSP support for ~java-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports eclipse.jdt.ls). *Incompatible with [[doom-module:][+meghanada]].*
- +meghanada ::
Enable [[doom-package:][meghanada-mode]]. *Incompatible with [[doom-module:][+lsp]].*
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
The =+lsp= and =+meghanada= packages are mutually exclusive and do not work
together. At the time of writing the =+meghanada= is already configured whereas
=+lsp= needs to manual configuring.
** Packages
- [[doom-package:][android-mode]]
- [[doom-package:][groovy-mode]]
- [[doom-package:][meghanada]] if [[doom-module:][+meghanada]]
- if [[doom-module:][+eclim]]
- [[doom-package:][eclim]]
- [[doom-package:][company-emacs-eclim]] if [[doom-module:][:completion company]]
- if [[doom-module:][+lsp]] and not [[doom-module:][:tools lsp +eglot]]
- [[doom-package:][lsp-java]]
The =lsp= test runner requires that =:tools (debugger +lsp)= is enabled, as this
provides =dap-mode= which contains the Java test runner.
** Hacks
/No hacks documented for this module./
* Prerequisites
This module requires the Java SDK.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- [[https://www.oracle.com/java/technologies/downloads/][Java SDK]]
- The LSP test runner requires [[doom-module:][:tools debugger +lsp]] (requires [[doom-package:][dap-mode]])
** OpenJDK 11
*** Ubuntu
#+BEGIN_SRC sh
sudo apt-get install openjdk-11-jdk-headless
#+END_SRC
#+begin-src sh
apt-get install openjdk-11-jdk-headless
#+end_src
*** Fedora
#+BEGIN_SRC sh
sudo dnf install java-11-openjdk
#+END_SRC
#+begin_src sh
dnf install java-11-openjdk
#+end_src
** Oracle JDK 11
*** Ubuntu
#+BEGIN_SRC sh
sudo add-apt-repository ppa:linuxuprising/java
sudo apt update
sudo apt install oracle-java11-installer
sudo apt install oracle-java11-set-default
#+END_SRC
#+begin_src sh
add-apt-repository ppa:linuxuprising/java
apt update
apt install oracle-java11-installer
apt install oracle-java11-set-default
#+end_src
*** Fedora
#+BEGIN_SRC sh
#+begin_src sh
curl -O https://download.java.net/java/GA/jdk11/9/GPL/openjdk-11.0.2_linux-x64_bin.tar.gz
tar zxvf openjdk-11.0.2_linux-x64_bin.tar.gz
sudo mv jdk-11.0.2/ /usr/local/
#+END_SRC
#+end_src
Open =/etc/profile.d/jdk11.sh= as root and add
#+BEGIN_SRC sh
Open =/etc/profile.d/jdk11.sh= as root and add:
#+begin_src sh
export JAVA_HOME=/usr/local/jdk-11.0.2
export PATH=$PATH:$JAVA_HOME/bin
#+END_SRC
#+end_src
Save the file and source the file
#+BEGIN_SRC sh
Save the file and source it:
#+begin_src sh
source /etc/profile.d/jdk11.sh
java -version
#+END_SRC
#+end_src
** Multiple Java Versions
It is common to need support for multiple Java versions. You can use a generic
tool like [[https://github.com/shyiko/jabba][jabba]] to install and manage multiple Java versions on any OS.
To switch between Java versions in Doom, you can use [[https://github.com/direnv/direnv][direnv]] and the [[file:~/.emacs.d/modules/tools/direnv/README.org::+TITLE: tools/direnv][direnv module]]. To set a
Java version for a particular project, create a =.envrc= pointing to the Java
installation in the root of the project:
#+BEGIN_SRC conf-unix
To have a different version of Java per-project, it is recommended you use
[[https://github.com/direnv/direnv][direnv]] and [[doom-module:][:tools direnv]]; create a =.envrc= in the root of the project pointing
to the Java installation:
#+begin_src sh
PATH_add ~/.jabba/jdk/adopt@1.11.0-3
JAVA_HOME=~/.jabba/jdk/adopt@1.11.0-3
#+END_SRC
#+end_src
And then run =direnv allow .= in the project directory. If the =direnv= module
is enabled, then Doom will automatically source this environment before
executing the LSP server.
And then run ~$ direnv allow .~ in the project directory. The [[doom-module:][:tools direnv]]
module will automatically source this environment before activating LSP servers.
* Features
** =+lsp= features
According to [[https://github.com/emacs-lsp/lsp-java]] it adds
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
+ As you type reporting of parsing and compilation errors (via flycheck/[[https://github.com/emacs-lsp/lsp-ui][lsp-ui]])
+ Code completion - using [[https://github.com/tigersoldier/company-lsp][company-lsp]] or builtin complete-at-point
+ Javadoc hovers - using [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]]
+ Code actions - using [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]]
+ Code outline - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html][imenu]]
+ Code navigation - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html][xref]]
+ Code lens (references/implementations) - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html][xref]]
+ Highlights
+ Code formatting
+ Maven pom.xml project support
+ Limited Gradle support
+ Visual debugger - [[https://github.com/yyoncho/dap-mode/][dap-mode]]
+ Test runner - [[https://github.com/yyoncho/dap-mode/][dap-mode]]
+ Project explorer integration - [[https://github.com/Alexander-Miller/treemacs][treemacs]]
+ Integration with [[https://start.spring.io/][Spring Initializr]]
** [[doom-module:][+lsp]] features
According to [[https://github.com/emacs-lsp/lsp-java]], you get:
- As you type reporting of parsing and compilation errors (via [[doom-package:][flycheck]] or
[[doom-package:][lsp-ui]])
- Code completion ([[doom-package:][company-lsp]] or complete-at-point)
- Javadoc hovers ([[doom-package:][lsp-ui]])
- Code actions ([[doom-package:][lsp-ui]])
- Code outline ([[doom-package:][imenu]])
- Code navigation ([[doom-package:][xref]])
- Code lens for references/implementations ([[doom-package:][xref]])
- Highlights
- Code formatting
- Maven pom.xml project support
- Limited Gradle support
- Visual debugger ([[doom-package:][dap-mode]])
- Test runner ([[doom-package:][dap-mode]])
- Project explorer integration ([[doom-package:][treemacs]])
- Integration with [[https://start.spring.io/][Spring Initializr]]
** =+meghanada= features
According to [[https://github.com/mopemope/meghanada-emacs/]] it adds
According to [[https://github.com/mopemope/meghanada-emacs/]], you get:
- Auto-update server module
- [[https://gradle.org/][Gradle]] and [[http://maven.apache.org/][Maven]] and Eclipse project support
- No need build tool's plugin
- Run build tool task
- Compile your project
- Syntax check and analyze java source ([[doom-package:][flycheck-meghanada]])
- Support =Generic Types=
- Code completion with [[doom-package:][company-mode]] ([[doom-package:][company-meghanada]])
- Optimize import and sort
- Jump declaration
- Run [[http://www.junit.org/][JUnit]] test (include test runner)
- Diagnostic reporting with [[doom-package:][flycheck]] ([[doom-package:][flycheck-meghanada]])
- Show symbol's type info with [[doom-package:][eldoc]]
- Search references
- Full-featured text search
+ Auto-update server module
+ [[https://gradle.org/][Gradle]] and [[http://maven.apache.org/][Maven]] and Eclipse project support
+ No need build tool's plugin
+ Run build tool task
+ Compile your project
+ Syntax check and analyze java source (=flycheck-meghanada=)
+ Support =Generic Types=
+ Code completion with [[http://company-mode.github.io/][company-mode]] (=company-meghanada=)
+ Optimize import and sort
+ Jump declaration
+ Run [[http://www.junit.org/][JUnit]] test (include test runner)
+ Diagnostic reporting with [[http://flycheck.org/][flycheck]] (=flycheck-meghanada=)
+ Show symbol's type info with =el-doc=
+ Search references
+ Full-featured text search
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** =+lsp=
Install the eclipse server by executing =M-x lsp-install-server= and selecting
** [[doom-module:][+lsp]]
Install the eclipse server by executing ~M-x lsp-install-server~ and selecting
=jdtls=. After that any newly opened =java= files should start the LSP server
automatically.
To update the server, perform =SPC u M-x lsp-install-server=.
To update the server, perform ~SPC u M-x lsp-install-server~.
Note that if you change Java version you may need to remove the LSP server and
install it again. You can do this with =M-x +lsp/uninstall-server= followed by
=M-x lsp-install-server=.
install it again. You can do this with ~M-x +lsp/uninstall-server~ followed by
~M-x lsp-install-server~.
Enable the =:tools (debugger +lsp)= module to get test runner support.
Enable the [[doom-module:][:tools debugger +lsp]] module to get test runner support.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

264
modules/lang/javascript/README.org
View file

@ -1,146 +1,162 @@
#+TITLE: lang/javascript
#+DATE: January 16, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang javascript
#+subtitle: all(hope(abandon(ye(who(enter(here))))))
#+created: January 16, 2017
#+since: 1.3
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#packages][Packages]]
- [[#prerequisites][Prerequisites]]
- [[#macos][MacOS]]
- [[#arch-linux][Arch Linux]]
- [[#opensuse][openSUSE]]
- [[#troubleshooting][Troubleshooting]]
- [[#tide-sort-completions-by-kind-isnt-respected][~tide-sort-completions-by-kind~ isn't respected]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
* Description :unfold:
This module adds [[https://www.javascript.com/][JavaScript]] and [[https://www.typescriptlang.org/][TypeScript]] support to Doom Emacs.
* Description
This module adds JavaScript and TypeScript support.
- Code completion ([[doom-package:][tide]])
- REPL support ([[doom-package:][nodejs-repl]])
- Refactoring commands ([[doom-package:][js2-refactor]])
- Syntax checking ([[doom-package:][flycheck]])
- Browser code injection with [[doom-package:][skewer-mode]]
- Coffeescript & JSX support
- Jump-to-definitions and references support ([[doom-package:][xref]])
+ Code completion (tide)
+ REPL support (nodejs-repl)
+ Refactoring commands (js2-refactor)
+ Syntax checking (flycheck)
+ Browser code injection with skewer-mode
+ Coffeescript & JSX support
+ Jump-to-definitions and references support (xref)
** Maintainers
- [[doom-user:][@hlissner]]
** Module Flags
+ =+lsp= Enables LangServer support for this module. You must have =:tools lsp=
enabled for this to work, as well as the langserver (e.g.
typescript-language-server) installed on your system.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +lsp ::
Enable LSP support for ~js2-mode~, ~rjsx-mode~, JS in ~web-mode~, and
~typescript-mode~. Requires [[doom-module:][:tools lsp]] and a langserver (supports ts-ls and
deno-ls).
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
** Packages
+ [[https://github.com/defunkt/coffee-mode][coffee-mode]]
+ [[https://github.com/mooz/js2-mode][js2-mode]]
+ [[https://github.com/felipeochoa/rjsx-mode][rjsx-mode]]
+ [[https://github.com/emacs-typescript/typescript.el][typescript-mode]]
+ [[https://github.com/magnars/js2-refactor.el][js2-refactor]]
+ [[https://github.com/mojochao/npm-mode][npm-mode]]
+ [[https://github.com/abicky/nodejs-repl.el][nodejs-repl]]
+ [[https://github.com/skeeto/skewer-mode][skewer-mode]]
+ [[https://github.com/ananthakumaran/tide][tide]]
+ [[https://github.com/NicolasPetton/xref-js2][xref-js2]]*
- [[doom-package:][js2-refactor]]
- [[doom-package:][nodejs-repl]]
- [[doom-package:][npm-mode]]
- [[doom-package:][rjsx-mode]]
- [[doom-package:][skewer-mode]] (DEPRECATED)
- [[doom-package:][tide]]
- [[doom-package:][typescript-mode]]
- [[doom-package:][xref-js2]] if [[doom-module:][:tools lookup]]
* Prerequisites
Many of this modules' plugins require ~node~ and either ~npm~ or ~yarn~
installed.
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** MacOS
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew install node
#+END_SRC
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
** Arch Linux
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --needed --noconfirm -S nodejs npm
#+END_SRC
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
** openSUSE
#+BEGIN_SRC sh :dir /sudo::
sudo zypper install nodejs npm
#+END_SRC
This module requires [[https://nodejs.org/en/][NodeJS]] and one of [[https://www.npmjs.com/][NPM]] or [[https://yarnpkg.com/][Yarn]] in your =$PATH=.
* Troubleshooting
** ~tide-sort-completions-by-kind~ isn't respected
The =:completion company= module uses =company-prescient= to sort completion by
[[https://developer.mozilla.org/en-US/docs/Mozilla/Tech/Places/Frecency_algorithm][frecency]], which overrules specialized sorting provided by some company backends
(like ~company-tide~).
- MacOS: ~$ brew install node~
- Arch Linux: ~$ pacman --needed --noconfirm -S nodejs npm~
- openSUSE: ~$ zypper install nodejs npm~
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
~rjsx-mode~ is used for all javascript buffers.
* Appendix
** Commands
*** JS2-mode
*** rjsx-mode
| command | key / ex command | description |
|----------------------------------+------------------+------------------------------------------------------------|
| ~+javascript/open-repl~ | =:repl= | Open the NodeJS REPL (or send the current selection to it) |
| ~+javascript/skewer-this-buffer~ | =SPC m S= | Attaches a browser to the current buffer |
| ~+javascript/open-repl~ | ~:repl~ | Open the NodeJS REPL (or send the current selection to it) |
| ~+javascript/skewer-this-buffer~ | [[kbd:][<localleader> S]] | Attaches a browser to the current buffer |
*** Tide
| command | key / ex command | description |
|-------------------------+------------------+------------------------|
| ~tide-restart-server~ | =SPC m R= | Restart tide server |
| ~tide-reformat~ | =SPC m f= | Reformat region |
| ~tide-rename-symbol~ | =SPC m r r s= | Rename symbol at point |
| ~tide-organize-imports~ | =SPC m r o i= | Organize imports |
| command | key / ex command | description |
|-------------------------+---------------------+------------------------|
| ~tide-restart-server~ | [[kbd:][<localleader> R]] | Restart tide server |
| ~tide-reformat~ | [[kbd:][<localleader> f]] | Reformat region |
| ~tide-rename-symbol~ | [[kbd:][<localleader> r r s]] | Rename symbol at point |
| ~tide-organize-imports~ | [[kbd:][<localleader> r o i]] | Organize imports |
*** Refactoring (js2-refactor-mode)
| command | key / ex command | description |
|---------------------------------------------------+------------------+--------------------------------------------------------------------------------------------------------------------|
| ~js2r-expand-node-at-point~ | =SPC m r e e= | Expand bracketed list according to node type at point |
| ~js2r-contract-node-at-point~ | =SPC m r c c= | Contract bracketed list according to node type at point |
| ~js2r-extract-function~ | =SPC m r e f= | Extracts the marked expressions out into a new named function. |
| ~js2r-extract-method~ | =SPC m r e m= | Extracts the marked expressions out into a new named method in an object literal. |
| ~js2r-toggle-function-expression-and-declaration~ | =SPC m r t f= | Toggle between function name() {} and var name = function (); |
| ~js2r-toggle-arrow-function-and-expression~ | =SPC m r t a= | Toggle between function expression to arrow function. |
| ~js2r-toggle-function-async~ | =SPC m r t s= | Toggle between an async and a regular function. |
| ~js2r-introduce-parameter~ | =SPC m r i p= | Changes the marked expression to a parameter in a local function. |
| ~js2r-localize-parameter~ | =SPC m r l p= | Changes a parameter to a local var in a local function. |
| ~js2r-wrap-buffer-in-iife~ | =SPC m r w i= | Wraps the entire buffer in an immediately invoked function expression |
| ~js2r-inject-global-in-iife~ | =SPC m r i g= | Creates a shortcut for a marked global by injecting it in the wrapping immediately invoked function expression |
| ~js2r-add-to-globals-annotation~ | =SPC m r a g= | Creates a /*global */ annotation if it is missing, and adds the var at point to it. |
| ~js2r-extract-var~ | =SPC m r e v= | Takes a marked expression and replaces it with a var. |
| ~js2r-extract-let~ | =SPC m r e l= | Similar to extract-var but uses a let-statement. |
| ~js2r-extract-const~ | =SPC m r e c= | Similar to extract-var but uses a const-statement. |
| ~js2r-inline-var~ | =SPC m r i v= | Replaces all instances of a variable with its initial value. |
| ~js2r-rename-var~ | =SPC m r r v= | Renames the variable on point and all occurrences in its lexical scope. |
| ~js2r-var-to-this~ | =SPC m r v t= | Changes local var a to be this.a instead. |
| ~js2r-arguments-to-object~ | =SPC m r a o= | Replaces arguments to a function call with an object literal of named arguments. |
| ~js2r-ternary-to-if~ | =SPC m r 3 i= | Converts ternary operator to if-statement. |
| ~js2r-split-var-declaration~ | =SPC m r s v= | Splits a var with multiple vars declared, into several var statements. |
| ~js2r-split-string~ | =SPC m r s s= | Splits a string. |
| ~js2r-string-to-template~ | =SPC m r s t= | Converts a string into a template string. |
| ~js2r-unwrap~ | =SPC m r u w= | Replaces the parent statement with the selected region. |
| ~js2r-log-this~ | =SPC m r l t= | Adds a console.log() statement for what is at point (or region). With a prefix argument, use JSON pretty-printing. |
| ~js2r-debug-this~ | =SPC m r d t= | Adds a debug() statement for what is at point (or region). |
| ~js2r-forward-slurp~ | =SPC m r s l= | Moves the next statement into current function, if-statement, for-loop or while-loop. |
| ~js2r-forward-barf~ | =SPC m r b a= | Moves the last child out of current function, if-statement, for-loop or while-loop. |
| ~js2r-kill~ | =SPC m r k= | Kills to the end of the line, but does not cross semantic boundaries. |
| command | key / ex command | description |
|---------------------------------------------------+---------------------+--------------------------------------------------------------------------------------------------------------------|
| ~js2r-expand-node-at-point~ | [[kbd:][<localleader> r e e]] | Expand bracketed list according to node type at point |
| ~js2r-contract-node-at-point~ | [[kbd:][<localleader> r c c]] | Contract bracketed list according to node type at point |
| ~js2r-extract-function~ | [[kbd:][<localleader> r e f]] | Extracts the marked expressions out into a new named function. |
| ~js2r-extract-method~ | [[kbd:][<localleader> r e m]] | Extracts the marked expressions out into a new named method in an object literal. |
| ~js2r-toggle-function-expression-and-declaration~ | [[kbd:][<localleader> r t f]] | Toggle between function name() {} and var name = function (); |
| ~js2r-toggle-arrow-function-and-expression~ | [[kbd:][<localleader> r t a]] | Toggle between function expression to arrow function. |
| ~js2r-toggle-function-async~ | [[kbd:][<localleader> r t s]] | Toggle between an async and a regular function. |
| ~js2r-introduce-parameter~ | [[kbd:][<localleader> r i p]] | Changes the marked expression to a parameter in a local function. |
| ~js2r-localize-parameter~ | [[kbd:][<localleader> r l p]] | Changes a parameter to a local var in a local function. |
| ~js2r-wrap-buffer-in-iife~ | [[kbd:][<localleader> r w i]] | Wraps the entire buffer in an immediately invoked function expression |
| ~js2r-inject-global-in-iife~ | [[kbd:][<localleader> r i g]] | Creates a shortcut for a marked global by injecting it in the wrapping immediately invoked function expression |
| ~js2r-add-to-globals-annotation~ | [[kbd:][<localleader> r a g]] | Creates a /*global */ annotation if it is missing, and adds the var at point to it. |
| ~js2r-extract-var~ | [[kbd:][<localleader> r e v]] | Takes a marked expression and replaces it with a var. |
| ~js2r-extract-let~ | [[kbd:][<localleader> r e l]] | Similar to extract-var but uses a let-statement. |
| ~js2r-extract-const~ | [[kbd:][<localleader> r e c]] | Similar to extract-var but uses a const-statement. |
| ~js2r-inline-var~ | [[kbd:][<localleader> r i v]] | Replaces all instances of a variable with its initial value. |
| ~js2r-rename-var~ | [[kbd:][<localleader> r r v]] | Renames the variable on point and all occurrences in its lexical scope. |
| ~js2r-var-to-this~ | [[kbd:][<localleader> r v t]] | Changes local var a to be this.a instead. |
| ~js2r-arguments-to-object~ | [[kbd:][<localleader> r a o]] | Replaces arguments to a function call with an object literal of named arguments. |
| ~js2r-ternary-to-if~ | [[kbd:][<localleader> r 3 i]] | Converts ternary operator to if-statement. |
| ~js2r-split-var-declaration~ | [[kbd:][<localleader> r s v]] | Splits a var with multiple vars declared, into several var statements. |
| ~js2r-split-string~ | [[kbd:][<localleader> r s s]] | Splits a string. |
| ~js2r-string-to-template~ | [[kbd:][<localleader> r s t]] | Converts a string into a template string. |
| ~js2r-unwrap~ | [[kbd:][<localleader> r u w]] | Replaces the parent statement with the selected region. |
| ~js2r-log-this~ | [[kbd:][<localleader> r l t]] | Adds a console.log() statement for what is at point (or region). With a prefix argument, use JSON pretty-printing. |
| ~js2r-debug-this~ | [[kbd:][<localleader> r d t]] | Adds a debug() statement for what is at point (or region). |
| ~js2r-forward-slurp~ | [[kbd:][<localleader> r s l]] | Moves the next statement into current function, if-statement, for-loop or while-loop. |
| ~js2r-forward-barf~ | [[kbd:][<localleader> r b a]] | Moves the last child out of current function, if-statement, for-loop or while-loop. |
| ~js2r-kill~ | [[kbd:][<localleader> r k]] | Kills to the end of the line, but does not cross semantic boundaries. |
*** skewer-mode
**** general
| command | key / ex command | description |
|-------------------------------+------------------+---------------------------------------|
| ~skewer-eval-last-expression~ | =SPC m s E= | Evaluate last expression |
| ~skewer-eval-defun~ | =SPC m s e= | Evaluate function definition at point |
| ~skewer-load-buffer~ | =SPC m s f= | Load buffer into REPL |
| command | key / ex command | description |
|-------------------------------+-------------------+---------------------------------------|
| ~skewer-eval-last-expression~ | [[kbd:][<localleader> s E]] | Evaluate last expression |
| ~skewer-eval-defun~ | [[kbd:][<localleader> s e]] | Evaluate function definition at point |
| ~skewer-load-buffer~ | [[kbd:][<localleader> s f]] | Load buffer into REPL |
**** css
| command | key / ex command | description |
|---------------------------------------+------------------+-------------------------------|
| ~skewer-css-eval-current-declaration~ | =SPC m s e= | Evaluate declaration at point |
| ~skewer-css-eval-current-rule~ | =SPC m s r= | Evaluate rule at point |
| ~skewer-css-eval-buffer~ | =SPC m s b= | Evaluate buffer |
| ~skewer-css-clear-all~ | =SPC m s c= | Clear all rules |
| command | key / ex command | description |
|---------------------------------------+-------------------+-------------------------------|
| ~skewer-css-eval-current-declaration~ | [[kbd:][<localleader> s e]] | Evaluate declaration at point |
| ~skewer-css-eval-current-rule~ | [[kbd:][<localleader> s r]] | Evaluate rule at point |
| ~skewer-css-eval-buffer~ | [[kbd:][<localleader> s b]] | Evaluate buffer |
| ~skewer-css-clear-all~ | [[kbd:][<localleader> s c]] | Clear all rules |
**** html
| command | key / ex command | description |
|------------------------+------------------+-----------------------|
| ~skewer-html-eval-tag~ | =SPC m s e= | Evaluate tag at point |
| command | key / ex command | description |
|------------------------+-------------------+-----------------------|
| ~skewer-html-eval-tag~ | [[kbd:][<localleader> s e]] | Evaluate tag at point |
*** npm-mode
| command | key / ex command | description |
|---------------------------------+------------------+------------------------------------------------------------------|
| ~npm-mode-npm-init~ | =SPC m n n= | Initialize npm project |
| ~npm-mode-npm-install~ | =SPC m n i= | Install npm package |
| ~npm-mode-npm-install-save~ | =SPC m n s= | Install npm package and save to package.json |
| ~npm-mode-npm-install-save-dev~ | =SPC m n d= | Install npm package and save to package.json as a dev dependency |
| ~npm-mode-npm-uninstall~ | =SPC m n u= | Uninstall npm package |
| ~npm-mode-npm-list~ | =SPC m n l= | List npm packages |
| ~npm-mode-npm-run~ | =SPC m n r= | Run npm task |
| ~npm-mode-visit-project-file~ | =SPC m n v= | Find file in npm project |
| command | key / ex command | description |
|---------------------------------+-------------------+------------------------------------------------------------------|
| ~npm-mode-npm-init~ | [[kbd:][<localleader> n n]] | Initialize npm project |
| ~npm-mode-npm-install~ | [[kbd:][<localleader> n i]] | Install npm package |
| ~npm-mode-npm-install-save~ | [[kbd:][<localleader> n s]] | Install npm package and save to package.json |
| ~npm-mode-npm-install-save-dev~ | [[kbd:][<localleader> n d]] | Install npm package and save to package.json as a dev dependency |
| ~npm-mode-npm-uninstall~ | [[kbd:][<localleader> n u]] | Uninstall npm package |
| ~npm-mode-npm-list~ | [[kbd:][<localleader> n l]] | List npm packages |
| ~npm-mode-npm-run~ | [[kbd:][<localleader> n r]] | Run npm task |
| ~npm-mode-visit-project-file~ | [[kbd:][<localleader> n v]] | Find file in npm project |
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

77
modules/lang/json/README.org
View file

@ -1,40 +1,57 @@
#+TITLE: lang/json
#+DATE: April 23, 2020
#+SINCE: v3.0.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang json
#+subtitle: At least it ain't XML
#+created: April 23, 2020
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description
This module provides JSON support.
* Description :unfold:
This module adds [[https://www.json.org/json-en.html][JSON]] support to Doom Emacs.
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+lsp= Enable integration with LSP servers, if one is available. Requires the
=:tools lsp= module to be enabled.
** Module flags
- +lsp ::
Enable LSP support for ~json-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/vscode-langservers/vscode-json-languageserver][vscode-json-languageserver]]).
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
** Plugins
+ [[https://github.com/joshwnj/json-mode][json-mode]]
+ [[https://github.com/Sterlingg/json-snatcher][json-snatcher]]
** Packages
- [[doom-package:][counsel-jq]] if [[doom-module:][:completion ivy]]
- [[doom-package:][json-mode]]
- [[doom-package:][json-snatcher]]
* Prerequisites
This module has no prerequisites.
** Hacks
/No hacks documented for this module./
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
# How to configure this module, including common problems and how to address them.
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Troubleshooting
# Common issues and their solution, or places to look for help.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

176
modules/lang/julia/README.org
View file

@ -1,109 +1,131 @@
#+TITLE: lang/julia
#+DATE: April 8, 2020
#+SINCE: v1.3
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang julia
#+subtitle: A better, faster MATLAB
#+created: April 08, 2020
#+since: 1.3
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#language-server][Language Server]]
- [[#lsp-julia][~lsp-julia~]]
- [[#eglot-jl][~eglot-jl~]]
- [[#features][Features]]
- [[#language-server-1][Language Server]]
- [[#configuration][Configuration]]
- [[#change-the-default-environment-for-the-julia-language-server][Change the default environment for the Julia language server]]
* Description
* Description :unfold:
This module adds support for [[https://julialang.org/][the Julia language]] to Doom Emacs.
+ Syntax highlighting and latex symbols from ~julia-mode~
+ REPL integration from ~julia-repl~
+ Code completion and syntax checking, requires ~:tools lsp~ and ~+lsp~
- Syntax highlighting and latex symbols from [[doom-package:][julia-mode]]
- REPL integration from [[doom-package:][julia-repl]]
- Code completion and syntax checking, requires [[doom-module:][:tools lsp]] and [[doom-module:][+lsp]]
** Module Flags
+ =+lsp= Enable LSP server support.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/JuliaEditorSupport/julia-emacs/][julia-mode]]
+ [[https://github.com/tpapp/julia-repl][julia-repl]]
+ =+lsp= and =:tools lsp=
+ [[https://github.com/non-jedi/lsp-julia][lsp-julia]]
+ [[https://github.com/emacs-lsp/lsp-mode][lsp]]
+ =+lsp= and =:tools lsp +eglot=
+ [[https://github.com/non-jedi/eglot-jl][eglot-jl]]
+ [[https://github.com/joaotavora/eglot][eglot]]
** Module flags
- +lsp ::
Enable LSP support for ~julia-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports LanguageServer.jl).
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
* Prerequisites
This module requires =julia= and an language server if =+lsp= is enabled.
** Packages
- [[doom-package:][julia-mode]]
- [[doom-package:][julia-repl]]
- if [[doom-package:][+lsp]]
- if [[doom-module:][:tools lsp]]
- [[doom-package:][lsp-julia]]
- [[doom-package:][lsp]]
- if [[doom-module:][:tools lsp +eglot]]
- [[doom-package:][eglot-jl]]
- [[doom-package:][eglot]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires [[https://julialang.org/][Julia]] and an language server if [[doom-module:][+lsp]] is enabled.
** Language Server
~+lsp~ requires ~LanguageServer.jl~ and ~SymbolServer.jl~. The =lsp-julia= and
=eglot-jl= packages both come bundled with their own versions of these servers,
[[doom-module:][+lsp]] requires ~LanguageServer.jl~ and ~SymbolServer.jl~. The [[doom-package:][lsp-julia]] and
[[doom-package:][eglot-jl]] packages both come bundled with their own versions of these servers,
which is used by default. If you're happy with that, no further configuration is
necessary.
However, to use your own installation you will need to install then configure
them. To install them, execute these commands in a Julia REPL:
#+BEGIN_SRC julia
#+begin_src julia
using Pkg
Pkg.add("LanguageServer")
Pkg.add("SymbolServer")
#+END_SRC
#+end_src
Then configure =lsp-julia= or =eglot-jl= depending on whether you have enabled
=:tools lsp= or =:tools (lsp +eglot)=, respectively:
Then configure [[doom-package:][lsp-julia]] or [[doom-package:][eglot-jl]] depending on whether you have enabled
[[doom-module:][:tools lsp]] or [[doom-module:][:tools lsp +eglot]], respectively:
*** ~lsp-julia~
To instruct =lsp-julia= not to use the built-in package:
#+BEGIN_SRC elisp
;; ~/.doom.d/config.el
*** =lsp-julia=
To instruct [[doom-package:][lsp-julia]] not to use the built-in package:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq lsp-julia-package-dir nil)
#+END_SRC
#+end_src
To find your installation of ~LanguageServer.jl~, ~eglot-jl~ needs to know the
environment in which it is installed. This is set to v1.0 by default as it is
To find your installation of ~LanguageServer.jl~, [[doom-package:][lsp-julia]] needs to know the
environment in which it is installed. This is set to v1.6 by default as it is
the current LTS:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! lsp-julia
(setq lsp-julia-default-environment "~/.julia/environments/v1.6"))
#+end_src
#+BEGIN_SRC elisp
(setq lsp-julia-default-environment "~/.julia/environments/v1.0")
#+END_SRC
*** ~eglot-jl~
To find your installation of ~LanguageServer.jl~, ~eglot-jl~ must know the
environment in which it is installed. This is set to v1.0 by default as it is
*** =eglot-jl=
To find your installation of ~LanguageServer.jl~, [[doom-package:][eglot-jl]] must know the
environment in which it is installed. This is set to v1.6 by default as it is
the current LTS:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq eglot-jl-language-server-project "~/.julia/environments/v1.6")
#+end_src
#+BEGIN_SRC elisp
;; ~/.doom.d/config.el
(setq eglot-jl-language-server-project "~/.julia/environments/v1.0")
#+END_SRC
But to let ~eglot-jl~ use the environment bundled with it, set it to
But to let [[doom-package:][eglot-jl]] use the environment bundled with it, set it to
~eglot-jl-base~ instead:
#+BEGIN_SRC elisp
;; ~/.doom.d/config.el
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! eglot-jl
(setq eglot-jl-language-server-project eglot-jl-base))
#+END_SRC
#+end_src
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
** Language Server
~+lsp~ adds code completion, syntax checking, formatting and other ~lsp-mode~ or
~eglot~ features. It requires ~LanguageServer.jl~, the installation of which is
[[doom-module:][+lsp]] adds code completion, syntax checking, formatting and other [[doom-package:][lsp-mode]] or
[[doom-package:][eglot]] features. It requires ~LanguageServer.jl~, the installation of which is
described above.
* Configuration
** Change the default environment for the Julia language server
~lsp-julia~ requires a variable be set for the Julia environment. This is set to
v1.0 by default as it is the current LTS.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
#+BEGIN_SRC elisp
;; ~/.doom.d/config.el
(setq lsp-julia-default-environment "~/.julia/environments/v1.0")
#+END_SRC
** Change the default environment for the Julia language server
[[doom-package:][lsp-julia]] requires a variable be set for the Julia environment. This is set to
v1.6 by default as it is the current LTS:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! lsp-julia
(setq lsp-julia-default-environment "~/.julia/environments/v1.6"))
#+end_src
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

73
modules/lang/kotlin/README.org
View file

@ -1,36 +1,55 @@
#+TITLE: lang/kotlin
#+DATE: March 28, 2019
#+SINCE: v3.0.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang kotlin
#+subtitle: A Java(Script) that won't depress you
#+created: March 28, 2019
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module adds [[https://kotlinlang.org/][Kotlin]] support to Doom Emacs.
* Description
This module adds Kotlin support to Emacs.
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ =+lsp= Enables integration with [[https://github.com/emacs-lsp/lsp-mode][kotlin-language-server]]. This requires the
=:tools lsp= module.
** Module flags
- +lsp ::
Enable LSP support for ~kotlin-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports [[https://github.com/emacs-lsp/lsp-mode][kotlin-language-server]]).
** Plugins
+ kotlin-mode
+ flycheck-kotlin
** Packages
- [[doom-package:][flycheck-kotlin]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][kotlin-mode]]
* Prerequisites
TODO
** Hacks
/No hacks documented for this module./
* Features
TODO
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Configuration
TODO
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
#+begin_quote
🔨 /This module's prerequisites are not documented./ [[doom-contrib-module:][Document them?]]
#+end_quote
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
TODO
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

183
modules/lang/latex/README.org
View file

@ -1,98 +1,112 @@
#+TITLE: lang/latex
#+DATE: January 16, 2017
#+SINCE: v1.3
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang latex
#+subtitle: Writing papers in Emacs has never been so fun
#+created: January 16, 2017
#+since: 1.3
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#ubuntu][Ubuntu]]
- [[#arch-linux][Arch Linux]]
- [[#macos][macOS]]
- [[#nixos][NixOS]]
- [[#features][Features]]
- [[#customization][Customization]]
- [[#specifying-the-location-of-a-bibtex-file--corresponding-pdfs][Specifying the location of a bibtex file & corresponding PDFs]]
- [[#changing-the-pdfs-viewer][Changing the PDFs viewer]]
- [[#using-cdlatexs-snippets-despite-having-yasnippet][Using cdlatex's snippets despite having yasnippet]]
* Description
* Description :unfold:
Provide a helping hand when working with LaTeX documents.
+ Sane defaults
+ Fontification of many popular commands
+ Pretty indentation of wrapped lines using the ~adaptive-wrap~ package
+ Spell checking with ~flycheck~
+ Change PDF viewer to Okular or ~latex-preview-pane~
+ Bibtex editor
+ Autocompletion using ~company-mode~
+ Compile your .tex code only once using LatexMk
- Sane defaults
- Fontification of many popular commands
- Pretty indentation of wrapped lines using the [[doom-package:][adaptive-wrap]] package
- Spell checking with [[doom-package:][flycheck]]
- Change PDF viewer to Okular or [[doom-package:][latex-preview-pane]]
- Bibtex editor
- Autocompletion using [[doom-package:][company-mode]]
- Compile your =.tex= code only once using LatexMk
** Module Flags
+ =+latexmk= Use LatexMk instead of LaTeX to compile documents.
+ =+cdlatex= Enable [[https://github.com/cdominik/cdlatex][cdlatex]] for fast math insertion.
+ =+lsp= Start LSP automatically in `tex-mode-hook`. This requires the =:tools
lsp= module. Supported servers are `digestif` and `TexLab`.
+ =+fold= Use TeX-fold (from auctex) to fold LaTeX macros to unicode, and make
folding hook-based and less manual.
** Maintainers
- [[doom-user:][@tecosaur]]
- [[doom-user:][@ymarco]]
** Plugins
+ [[http://www.gnu.org/software/auctex/][auctex]]
+ [[http://elpa.gnu.org/packages/adaptive-wrap.html][adaptive-wrap]]
+ [[https://github.com/iyefrat/evil-tex][evil-tex]] (when =:editor evil +everywhere=)
+ [[https://github.com/jsinglet/latex-preview-pane][latex-preview-pane]]
+ [[https://github.com/tom-tan/auctex-latexmk][auctex-latexmk]]*
+ [[https://github.com/alexeyr/company-auctex][company-auctex]]*
+ [[https://github.com/TheBB/company-reftex][company-reftex]]*
+ [[https://github.com/vspinu/company-math][company-math]]*
+ [[https://github.com/cdominik/cdlatex][cdlatex]] (=+cdlatex=)
[[doom-contrib-maintainer:][Become a maintainer?]]
* Prerequisites
You will need ghostscript and a latex compiler. All this is provided by
the =texlive= bundle, available through many OS package managers.
** Module flags
- +cdlatex ::
Enable [[doom-package:][cdlatex]] for fast math insertion.
- +fold ::
Use TeX-fold (from [[doom-package:][auctex]]) to fold LaTeX macros to unicode, and make folding
hook-based and less manual.
- +latexmk ::
Use LatexMk instead of LaTeX to compile documents.
- +lsp ::
Enable LSP support in latex buffers. Requires [[doom-module:][:tools lsp]] and a langserver
(supports digestif and TexLab).
** Packages
- [[doom-package:][adaptive-wrap]]
- [[doom-package:][auctex]]
- [[doom-package:][auctex-latexmk]] if [[doom-module:][+latexmk]]
- [[doom-package:][cdlatex]] if [[doom-module:][+cdlatex]]
- [[doom-package:][evil-tex]] if [[doom-module:][:editor evil +everywhere]]
- [[doom-package:][latex-preview-pane]]
- if [[doom-module:][:completion company]]
- [[doom-package:][company-auctex]]
- [[doom-package:][company-math]]
- [[doom-package:][company-reftex]]
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires ghostscript and a latex compiler. These are provided by the
=texlive= bundle, available through many OS package managers.
#+begin_quote
🚧 Ghostscript <= 9.27 is [[/auctex/manual/preview-latex/No-images-are-displayed-with-gs-9_002e27-and-earlier.html][reportedly buggy]] and doesn't work with auctex's math
previews. (You can check you ghostscript version with ~$ gs --version~.)
Most package managers already have newer versions, but if not you might have
to build gs from source.
#+end_quote
Ghostscript <= 9.27 is [[https://www.gnu.org/software/auctex/manual/preview-latex/No-images-are-displayed-with-gs-9_002e27-and-earlier.html][reported buggy]] and doesn't work with auctex's math
previews. (You can check you ghostscript version with ~gs --version~.) Most
package managers already have newer versions, but if not you might have to build
gs from source.
** Ubuntu
#+BEGIN_SRC sh
#+begin_src sh
apt-get install texlive
#+END_SRC
#+end_src
** Arch Linux
#+BEGIN_SRC sh
#+begin_src sh
pacman -S texlive-core
#+END_SRC
#+end_src
** TODO macOS
#+BEGIN_SRC sh
#+begin_src sh
brew install --cask basictex
# If the above doesn't work, then
brew install --cask mactex # WARNING: large 4gb download!
#+END_SRC
#+end_src
#+begin_quote
This has not been verified.
🔨 This has not been verified.
#+end_quote
** NixOS
#+BEGIN_SRC nix
#+begin_src nix
environment.systemPackages = [ pkgs.texlive.combined.scheme-medium ];
#+END_SRC
#+end_src
* TODO Features
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Customization
* Configuration
** Specifying the location of a bibtex file & corresponding PDFs
Reftex has a variable that allow you to
specify where it should find your bibliography file(s):
#+BEGIN_SRC emacs-lisp
Reftex has a variable that allow you to specify where it should find your
bibliography file(s):
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq reftex-default-bibliography "/your/bib/file.bib")
#+END_SRC
#+end_src
** Changing the PDFs viewer
This module provides integration for four supported pdf viewers. They are
@ -102,30 +116,41 @@ This module provides integration for four supported pdf viewers. They are
+ Sumatra PDF
+ Zathura
+ Okular
+ pdf-tools (requires =:tools pdf= module)
+ pdf-tools (requires [[doom-module:][:tools pdf]] module)
They are searched for in this order. See ~+latex-viewers~ to change the order,
or remove tools from the search altogether. If you want to exclusively use one
tool, for instance:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(setq +latex-viewers '(zathura))
#+END_SRC
#+end_src
If none of these tools are found, ~latex-preview-pane~ (uses ~DocView~ in Emacs)
is used as a fallback. You can use this exclusively by setting ~+latex-viewers~
to ~nil~.
** Using cdlatex's snippets despite having yasnippet
cdlatex has a snippet insertion capability which is disabled in favor of
yasnippet when using ~:editor snippets~. If you still wanna use it, simply rebind
the ~TAB~ key for cdlatex, which takes care of snippet-related stuff:
#+BEGIN_SRC emacs-lisp
[[doom-package:][cdlatex]] has a snippet insertion capability which is disabled in favor of
[[doom-package:][yasnippet]] when using [[doom-module:][:editor snippets]]. If you still wanna use it, simply rebind
the [[kbd:][TAB]] key for cdlatex, which takes care of snippet-related stuff:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(map! :map cdlatex-mode-map
:i "TAB" #'cdlatex-tab)
#+END_SRC
:i "TAB" #'cdlatex-tab)
#+end_src
This would favor yasnippet's expansion and cursor movement over cdlatex's
expansion and movement, but that shouldn't matter if you're not using yasnippet
in latex buffers.
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

55
modules/lang/lean/README.org Normal file
View file

@ -0,0 +1,55 @@
# -*- mode: doom-docs-org -*-
#+title: :lang lean
#+subtitle: For folks with too much to prove
#+created: September 10, 2019
#+since: 21.12.0 (#1759)
* Description :unfold:
This module adds support for the [[https://leanprover.github.io/about/][Lean programming language]] to Doom Emacs.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][lean-mode]]
- [[doom-package:][company-lean]] if [[doom-module:][:completion company]]
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
#+begin_quote
🔨 /This module's prerequisites are not documented./ [[doom-contrib-module:][Document them?]]
#+end_quote
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

96
modules/lang/ledger/README.org
View file

@ -1,56 +1,74 @@
#+TITLE: lang/ledger
#+DATE: October 13, 2019
#+SINCE: v2.0.4
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang ledger
#+subtitle: Be audit you can be
#+created: September 09, 2017
#+since: 2.0.6 (#194)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#configuration][Configuration]]
* Description
* Description :unfold:
This module adds support for [[https://www.ledger-cli.org/][ledger]] files. Ledger is a command line double-entry
accounting system that works with simple text files holding transactions in the
following format:
#+BEGIN_SRC ledger
#+begin_src ledger
2015/10/12 Exxon
Expenses:Auto:Gas $10.00
Liabilities:MasterCard $-10.00
#+END_SRC
#+end_src
This modules enables the following features:
+ Syntax and indentation support for ledger files
+ Add, edit, and delete transactions
+ Generate reports
+ Schedule transactions
+ Sort transactions
+ Display statistics about transactions
+ Display balance up to a point
- Syntax and indentation support for ledger files
- Add, edit, and delete transactions
- Generate reports
- Schedule transactions
- Sort transactions
- Display statistics about transactions
- Display balance up to a point
** Module Flags
This module provides no flags.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/purcell/flycheck-ledger][flycheck-ledger]]
+ [[https://github.com/atheriel/evil-ledger][evil-ledger]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][evil-ledger]] if [[doom-module:][:editor evil +everywhere]]
- [[doom-package:][flycheck-ledger]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][ledger-mode]]
** Hacks
This module sets ~ledger-clear-whole-transactions~ to ~t~ (default value is
~nil~). This results in ~ledger-toggle-current~ toggling the clear status of the
whole transaction instead of toggling just the current posting.
- This module sets ~ledger-clear-whole-transactions~ to ~t~ (default value is
~nil~). This results in ~ledger-toggle-current~ toggling the clear status of
the whole transaction instead of toggling just the current posting.
* Prerequisites
In order for ~flycheck-ledger~ to work and to be able to generate reports you
will need to install [[https://www.ledger-cli.org/][ledger]].
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Features
An in-depth list of features, how to use them, and their dependencies.
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires [[https://www.ledger-cli.org/][ledger]] to syntax check and generate reports from your
ledgers.
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
Please refer to ~ledger-mode~'s documentation for information on how to
configure it. You can do so within emacs with =C-h i=
configure it. You can do so within emacs with [[kbd:][C-h i]]
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

126
modules/lang/lua/README.org
View file

@ -1,57 +1,66 @@
#+TITLE: lang/lua
#+DATE: Jun 3, 2020
#+SINCE: v3.0
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang lua
#+subtitle: One-based indices? one-based indices
#+created: Jun 03, 2020
#+since: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#language-server-protocol-servers][Language Server Protocol servers]]
- [[#lsp-mode][LSP-mode]]
- [[#eglot][Eglot]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
- [[#install-lua-language-server][Install lua-language-server]]
* Description :unfold:
This module adds Lua support to Doom Emacs.
* Description
Adds Lua support to Doom Emacs
# A summary of what this module does.
+ REPL
+ Love2D specific functions
+ Moonscript support
- REPL
- Love2D specific functions
- Moonscript support
- Fennel support
** Maintainers
This module has no dedicated maintainers.
- [[doom-user:][@hlissner]]
** Module Flags
+ =+moonscript= Moonscript language support
+ =+fennel= Fennel language support
+ =+lsp= Language Server Protocol support
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
# A list of linked plugins
+ [[https://github.com/immerrr/lua-mode][lua-mode]]
+ [[https://github.com/k2052/moonscript-mode][moonscript-mode]] (=+moonscript=)
+ [[https://gitlab.com/technomancy/fennel-mode][fennel-mode]] (=+fennel=)
** Module flags
- +fennel ::
Enable support for the Fennel language.
- +lsp ::
Enable LSP support for ~lua-mode~. Requires [[doom-module:][:tools lsp]] and a langserver
(supports EmmyLua, lua-language-server, and lua-lsp).
- +moonscript ::
Enable support for the Moonscript language.
** Packages
- [[doom-package:][company-lua]] if [[doom-module:][:completion company]]
- [[doom-package:][fennel-mode]] if [[doom-module:][+fennel]]
- [[doom-package:][lua-mode]]
- if [[doom-module:][+moonscript]]
- [[doom-package:][flycheck-moonscript]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][moonscript-mode]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires Lua 5.1+ for most of its capabilities and, optionally, the
fennel and moonscript transpilers. An LSP server is also required for LSP
support.
* Prerequisites
** Language Server Protocol servers
LSP server support depends on which flavor of the =:tools lsp= module you have
installed (Eglot or LSP-mode).
LSP server support depends on which flavor of the [[doom-module:][:tools lsp]] module you have
installed ([[doom-package:][eglot]] or [[doom-package:][lsp-mode]]).
*** LSP-mode
Three servers are supported, ordered from highest to lowest priority:
+ [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua-LanguageServer]] :: Must be in =~/.emacs.d/.local/etc/lsp/EmmyLua-LS-all.jar=. See ~lsp-clients-emmy-lua-jar-path~ variable to change this.
+ [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in
=~/.config/emacs/.local/etc/lsp/lua-language-server/=. See
- [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua-LanguageServer]] :: Must be in
=$EMACSDIR/.local/etc/lsp/EmmyLua-LS-all.jar=. See
~lsp-clients-emmy-lua-jar-path~ variable to change this.
- [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in
=$EMACSDIR/.local/etc/lsp/lua-language-server/=. See
~lsp-clients-lua-language-server-bin~ variable to change this.
+ [[https://github.com/Alloyed/lua-lsp][lua-lsp]] :: Must be available in =~/.luarocks/bin/lua-lsp=. See
- [[https://github.com/Alloyed/lua-lsp][lua-lsp]] :: Must be available in =~/.luarocks/bin/lua-lsp=. See
~lsp-clients-lua-lsp-server-install-dir~ variable to change this.
[[https://emacs-lsp.github.io/lsp-mode/page/lsp-emmy-lua/][LSP-mode documentation]] has more information about setting up the server and the
@ -59,20 +68,35 @@ configuration variables correctly.
*** Eglot
Eglot currently only supports one of the above servers out of the box:
+ [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in
=~/.config/emacs/.local/etc/lsp/lua-language-server/=. See
~+lua-lsp-dir~ variable to change this.
=$EMACSDIR/.local/etc/lsp/lua-language-server/=. See ~+lua-lsp-dir~ variable
to change this.
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Configuration
- lua-lsp-dir :: This must be set when using =+lsp= and using
[[https://github.com/sumneko/lua-language-server][lua-language-server]]. This controls where the repository has been cloned and
built to finish the configuration of the server.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
- lua-lsp-dir :: This must be set when using [[doom-module:][+lsp]] and using [[https://github.com/sumneko/lua-language-server][lua-language-server]].
This controls where the repository has been cloned and built to finish the
configuration of the server.
* Troubleshooting
[[doom-report:][Report an issue?]]
** Install lua-language-server
A [[https://github.com/sumneko/lua-language-server/issues/60][catch-all issue]] has been created to gather help for installing
lua-language-server on non-VSCode platforms.
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

175
modules/lang/markdown/README.org
View file

@ -1,26 +1,10 @@
#+TITLE: lang/markdown
#+DATE: February 19, 2017
#+SINCE: 2.0
#+STARTUP: inlineimages
# -*- mode: doom-docs-org -*-
#+title: :lang markdown
#+subtitle: Write docs for people to ignore
#+created: February 19, 2017
#+since: 2.0.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#linters][Linters]]
- [[#markdown-preview][Markdown preview]]
- [[#markedjs][MarkedJS]]
- [[#pandoc][Pandoc]]
- [[#markdown][Markdown]]
- [[#multimarkdown][MultiMarkdown]]
- [[#features][Features]]
- [[#markdown-preview-1][Markdown preview]]
- [[#configuration][Configuration]]
- [[#changing-how-markdown-is-compiled][Changing how markdown is compiled]]
* Description
* Description :unfold:
This module provides Markdown support for Emacs.
#+begin_quote
@ -30,82 +14,97 @@ to structurally valid XHTML (or HTML).
Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a
software tool, written in Perl, that converts the plain text formatting to HTML.
See the Syntax page for details pertaining to Markdown’s formatting syntax. You
See the Syntax page for details pertaining to Markdown's formatting syntax. You
can try it out, right now, using the online Dingus.
The overriding design goal for Markdown’s formatting syntax is to make it as
The overriding design goal for Markdown's formatting syntax is to make it as
readable as possible. The idea is that a Markdown-formatted document should be
publishable as-is, as plain text, without looking like it’s been marked up with
tags or formatting instructions. While Markdown’s syntax has been influenced by
publishable as-is, as plain text, without looking like it's been marked up with
tags or formatting instructions. While Markdown's syntax has been influenced by
several existing text-to-HTML filters, the single biggest source of inspiration
for Markdown’s syntax is the format of plain text email. -- John Gruber
for Markdown's syntax is the format of plain text email. -- John Gruber
#+end_quote
** Module Flags
+ =+grip= Enables [[https://github.com/seagle0128/grip-mode][grip support]] (on =<localleader> p=), to provide live
github-style previews of your markdown (or org) files.
** Maintainers
- [[doom-user:][@hlissner]]
** Plugins
+ markdown-mode
+ markdown-toc
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +grip ::
Enable [[https://github.com/seagle0128/grip-mode][grip support]] (on [[kbd:][<localleader> p]]), to provide live github-style
previews of your markdown (or org) files.
** Packages
- [[doom-package:][edit-indirect]]
- [[doom-package:][evil-markdown]] if [[doom-module:][:editor evil +everywhere]]
- [[doom-package:][grip-mode]] if [[doom-module:][+grip]]
- [[doom-package:][markdown-mode]]
- [[doom-package:][markdown-toc]]
** Hacks
+ Flyspell has been configured not to spell check in code blocks, links, HTML
- [[doom-package:][flyspell]] has been configured not to spell check in code blocks, links, HTML
tags or references.
* Prerequisites
This module has two soft dependencies: a linter and a compiler (for previewing
markdown).
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- A linter (requires [[doom-module:][:checkers syntax]])
- A markdown compiler, for previewing Markdown
** Linters
Out of the box, flycheck recognizes these checkers for markdown-mode and
gfm-mode:
+ Markdown-specific
+ [[https://github.com/DavidAnson/markdownlint][markdownlint]] (~npm install markdownlint~)
+ [[https://github.com/markdownlint/markdownlint][mdl]] (~gem install mdl~)
+ General (natural language)
+ [[http://proselint.com/][proselint]]
- ~pip install proselint~
- Markdown-specific
- [[https://github.com/DavidAnson/markdownlint][markdownlint]] (~$ npm install markdownlint~)
- [[https://github.com/markdownlint/markdownlint][mdl]] (~$ gem install mdl~)
- General (natural language)
- [[http://proselint.com/][proselint]]
- ~$ pip install proselint~
- Or through your OS package manager
- MacOS: ~brew install proselint~
- Arch Linux: ~pacman -S proselint~
+ [[https://github.com/textlint/textlint][textlint]] (~npm install textlint~)
- MacOS: ~$ brew install proselint~
- Arch Linux: ~$ pacman -S proselint~
- [[https://github.com/textlint/textlint][textlint]] (~$ npm install textlint~)
** Markdown preview
** Markdown compiler
This module requires a markdown compiler in order for ~markdown-preview~ to
work. It will recognize and use one of the following executables, in this order
(you only need one):
+ [[https://github.com/markedjs/marked][markedjs]]: a markdown compiler "built for speed"
+ [[https://github.com/jgm/pandoc][pandoc]]: the universal markup transpiler
+ [[http://pell.portland.or.us/~orc/Code/discount/][markdown]]: there are various flavors of this compiler. This module will look
- [[https://github.com/markedjs/marked][markedjs]]: a markdown compiler "built for speed"
- [[https://github.com/jgm/pandoc][pandoc]]: the universal markup transpiler
- [[http://pell.portland.or.us/~orc/Code/discount/][markdown]]: there are various flavors of this compiler. This module will look
for these two:
+ John Gruber's [[https://daringfireball.net/projects/markdown/][original perl script]]
+ The C implementation called [[http://pell.portland.or.us/~orc/Code/discount/][discount]], by David Parsons
+ [[https://fletcher.github.io/MultiMarkdown-6/][multimarkdown]]: a compiler for a language that is a superset of Markdown, with
- John Gruber's [[https://daringfireball.net/projects/markdown/][original perl script]]
- The C implementation called [[http://pell.portland.or.us/~orc/Code/discount/][discount]], by David Parsons
- [[https://fletcher.github.io/MultiMarkdown-6/][multimarkdown]]: a compiler for a language that is a superset of Markdown, with
additional output formats and features.
*** MarkedJS
Not to be confused with [[https://marked2app.com/][the Marked 2 app]], marked is an npm package:
#+BEGIN_SRC sh
#+begin_src sh
npm install -g marked
#+END_SRC
#+end_src
*** Pandoc
Pandoc is the universal markup transpiler. It should be available through your
system package manager. For example:
+ MacOS: ~brew install pandoc~
+ Arch Linux: ~pacman -S pandoc~
+ MacOS: ~$ brew install pandoc~
+ Arch Linux: ~$ pacman -S pandoc~
*** Markdown
The C implementation of Markdown.pl, called =discount=, is available through
your OS's package manager:
+ MacOS: ~brew install discount~
+ Arch Linux: ~pacman -S discount~
+ MacOS: ~$ brew install discount~
+ Arch Linux: ~$ pacman -S discount~
The original perl script that discount is inspired from can be found on [[https://daringfireball.net/projects/markdown/][John
Gruber's website]].
@ -114,46 +113,62 @@ Gruber's website]].
See [[https://fletcher.github.io/MultiMarkdown-6/introduction.html][its documentation]] for details on what MultiMarkdown is. The compiler can be
installed through your OS's package manager:
+ MacOS: ~brew install multimarkdown~
+ MacOS: ~$ brew install multimarkdown~
+ Arch Linux: [[https://aur.archlinux.org/packages/multimarkdown/][multimarkdown]] is available on the AUR
* Features
** Markdown preview
~markdown-preview~ is bound to =<localleader> p=. This will open a preview of
your compiled markdown document in your browser.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Alternatively, you can use ~grip-mode~ through =+grip=.
** Markdown preview
~markdown-preview~ is bound to [[kbd:][<localleader> p]]. This will open a preview of your
compiled markdown document in your browser.
Alternatively, you can use ~grip-mode~ through [[doom-module:][+grip]].
* Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Changing how markdown is compiled
When ~markdown-preview~ is invoked (=<localleader> p=) it consults
When ~markdown-preview~ is invoked ([[kbd:][<localleader> p]]) it consults
~markdown-command~. Its default value (~#'+markdown-compile~) will consult
~+markdown-compile-functions~: a list of functions that take three arguments: the
start and end point in the current buffer to use as input, and an output buffer
to insert the result in.
~+markdown-compile-functions~: a list of functions that take three arguments:
the start and end point in the current buffer to use as input, and an output
buffer to insert the result in.
By default, the value of ~+markdown-compile-functions~ is:
#+BEGIN_SRC lisp
#+begin_src lisp
'(+markdown-compile-marked
+markdown-compile-pandoc
+markdown-compile-markdown
+markdown-compile-multimarkdown)
#+END_SRC
#+end_src
These functions will attempt to use the marked, pandoc and markdown executables,
if available. Changing this variable will control how markdown is compiled.
#+BEGIN_SRC elisp
if available. Changing this variable will control how markdown is compiled:
#+begin_src emacs-lisp
;; Add a new one
(add-hook '+markdown-compile-functions #'my-compile-function)
;; Or remove an existing one
(remove-hook '+markdown-compile-functions #'+markdown-compile-markdown)
#+END_SRC
#+end_src
Otherwise, you can change ~markdown-command~ directly:
#+BEGIN_SRC elisp
#+begin_src emacs-lisp
(setq markdown-command "markdown | smartypants")
#+END_SRC
#+end_src
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

90
modules/lang/nim/README.org
View file

@ -1,52 +1,74 @@
#+TITLE: :lang Nim
# -*- mode: doom-docs-org -*-
#+title: :lang nim
#+subtitle: Python + lisp at the speed of C
#+created: May 08, 2018
#+since: 21.12.0 (#568)
#+begin_quote
This module is a work in progress.
#+end_quote
* Description :unfold:
This module adds [[https://nim-lang.org][Nim]] support to Doom Emacs.
This module adds [[https://nim-lang.org][Nim]] support to Emacs.
- Code completion ([[doom-package:][nimsuggest]] + [[doom-package:][company]])
- Syntax checking ([[doom-package:][nimsuggest]] + [[doom-package:][flycheck]])
- Org babel support ([[doom-package:][ob-nim]])
+ Code completion (nimsuggest + company)
+ Syntax checking (nimsuggest + flycheck)
+ Babel support (~ob-nim~)
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
* Table of Contents :TOC:
- [[#module-flags][Module Flags]]
- [[#prerequisites][Prerequisites]]
- [[#nim][Nim]]
- [[#configuration][Configuration]]
** Module flags
/This module has no flags./
* Module Flags
This module provides no flags.
** Packages
- [[doom-package:][flycheck-nim]] if [[doom-module:][:checkers syntax]]
- [[doom-package:][nim-mode]]
* Prerequisites
+ ~nim~ (for building & evaluation)
+ ~nimsuggest~ (for code completion, syntax checking & jump-to-definition functionality)
** Hacks
- [[doom-package:][nimsuggest]] was modified to strip invalid characters from its temp file paths
(which would break nimsuggest on Windows systems).
- [[doom-package:][nim-mode]] was modified to fail gracefully if =nimsuggest= (the executable)
isn't available.
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- ~nim~, for building & evaluation.
- ~nimsuggest~, for code completion, syntax checking, and jump-to-definition
functionality.
** Nim
=choosenim= is an installer and version manager for the Nim programming
language. You can install the latest stable release of Nim by running the
following in your terminal and following the onscreen instructions:
#+BEGIN_SRC bash
#+begin_src sh
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
#+END_SRC
#+end_src
Alternatively, nim is usually available through your OS's package manager:
- MacOS: ~$ brew install nim~
- Arch Linux: ~$ pacman --needed --noconfirm -S nim nimble~
- openSUSE: ~$ zypper install nim~
*** MacOS
#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes")
brew install nim
#+END_SRC
* TODO Usage
#+begin_quote
🔨 This module has no usage documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
*** Arch Linux
#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes")
sudo pacman --needed --noconfirm -S nim nimble
#+END_SRC
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
*** openSUSE
#+BEGIN_SRC sh :dir /sudo::
sudo zypper install nim
#+END_SRC
* Troubleshooting
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Configuration
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

115
modules/lang/nix/README.org
View file

@ -1,57 +1,82 @@
#+TITLE: lang/nix
#+DATE: May 4, 2020
#+SINCE: v2.0.7
#+STARTUP: inlineimages nofold
# -*- mode: doom-docs-org -*-
#+title: :lang nix
#+subtitle: I hereby declare "nix geht mehr!"
#+created: December 02, 2017
#+since: 2.0.8 (#280)
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#keybindings][Keybindings]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module adds support for the Nix language to Doom Emacs, along with tools
for managing [[https://nixos.org/][Nix(OS)]].
* Description
Adds many tools for [[https://nixos.org/][Nix(OS)]] users in nice package for Doom users.
+ Syntax highlighting
+ Completion through ~company~ / ~helm~
+ Nix option lookup
+ Formatting (~nixfmt~)
Includes:
- Syntax highlighting
- Completion through [[doom-package:][company]] and/or [[doom-package:][helm]]
- Nix option lookup
- Formatting (~nixfmt~)
** Maintainers
This module has no dedicated maintainers.
- [[doom-user:][@hlissner]]
** Module Flags
This module provides no flags.
[[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/NixOS/nix-mode][nix-mode]]
+ [[https://github.com/jwiegley/nix-update-el][nix-update]]
** Module flags
- +tree-sitter ::
Leverages tree-sitter for better syntax highlighting and structural text
editing. Requires [[doom-module:][:tools tree-sitter]].
* Prerequisites
+ ~nixfmt~ is required to use formatting
+ If you have Nix(OS) installed it can be installed through Nix configuration ~environment.systemPackages = with pkgs; [ nixfmt ];~ (recommended)
+ Or through nix-env ~nix-env -iA nixpkgs.nixfmt~
+ Or through nix-shell ~nix-shell -f https://github.com/serokell/nixfmt/archive/master.tar.gz -i~
+ ~:editor format~ ~format-all~ also supports ~nixfmt~ so you can use that also to format Nix code, default binding is ~SPC c f~ in evil.
** Packages
- [[doom-package:][company-nixos-options]] if [[doom-module:][:completion company]]
- [[doom-package:][helm-nixos-options]] if [[doom-module:][:completion helm]]
- [[doom-package:][nix-mode]]
- [[doom-package:][nix-update]]
** Hacks
/No hacks documented for this module./
** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./
* TODO Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
This module requires:
- [[https://nixos.org/guides/install-nix.html][The Nix package manager]], for a variety of its features (besides syntax
highlighting).
- =nixfmt=, for automatic formatting (requires [[doom-module:][:editor format]]).
- *MacOS:* TODO
- *Arch Linux:* TODO
- *NixOS:* in ~pkgs.nixfmt~
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
** Keybindings
| Binding | Description |
|-------------------+----------------------|
| ~<localleader> b~ | ~nix-build~ |
| ~<localleader> f~ | ~nix-update-fetch~ |
| ~<localleader> o~ | ~+nix/lookup-option~ |
| ~<localleader> p~ | ~nix-format-buffer~ |
| ~<localleader> r~ | ~nix-repl-show~ |
| ~<localleader> s~ | ~nix-repl-shell~ |
| ~<localleader> u~ | ~nix-unpack~ |
| Binding | Description |
|-----------------+----------------------|
| [[kbd:][<localleader> b]] | ~nix-build~ |
| [[kbd:][<localleader> f]] | ~nix-update-fetch~ |
| [[kbd:][<localleader> o]] | ~+nix/lookup-option~ |
| [[kbd:][<localleader> p]] | ~nix-format-buffer~ |
| [[kbd:][<localleader> r]] | ~nix-repl-show~ |
| [[kbd:][<localleader> s]] | ~nix-repl-shell~ |
| [[kbd:][<localleader> u]] | ~nix-unpack~ |
* Configuration
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
+ There aren't any known problems.
/There are no known problems with this module./ [[doom-report:][Report one?]]
* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]
* TODO Appendix
#+begin_quote
🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote

Some files were not shown because too many files have changed in this diff Show more