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

docs(:tools): update READMEs to new format

Browse source
This commit is contained in:
Henrik Lissner 2021-10-16 01:29:27 +02:00 • committed by Henrik Lissner
parent a226655486
commit 6da20e45bd
21 changed files with 1401 additions and 748 deletions
Download patch file Download diff file Expand all files Collapse all files

8
modules/tools/README.org
View file

@ -1,10 +1,8 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-changelog-search:::tools nil][Changelog]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
← [[doom-module-index:][Back to module index]] ↖ [[doom-module-source:tools][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools
#+CREATED: July 29, 2021
#+SINCE: v21.12.0
#+SETUPFILE: ../../docs/.setupfile.org
#+SINCE: 21.12.0
* Description
Replace this with a description of what modules in this category are for,
including any important information (like load order constraints).
Modules that integrate external tools into Emacs.

55
modules/tools/ansible/README.org Normal file
View file

@ -0,0 +1,55 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools ansible][Issues]] ↖ [[doom-module-source:tools/ansible][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools ansible
#+SUBTITLE: Allow silly people to focus on silly things
#+CREATED: September 11, 2018
#+SINCE: 21.12.0 (#881)
* Description :unfold:
/(No description)/
** Maintainers
*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][ansible]]
- [[doom-package:][ansible-doc]]
- [[doom-package:][company-ansible]] if [[doom-module:][:completion company]]
- [[doom-package:][jinja2-mode]]
- [[doom-package:][yaml-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://www.ansible.com/][Ansible]].
* 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

169
modules/tools/debugger/README.org Normal file
View file

@ -0,0 +1,169 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools debugger][Issues]] ↖ [[doom-module-source:tools/debugger][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools debugger
#+SUBTITLE: Step through code to help you add bugs
#+CREATED: February 20, 2020
#+SINCE: 2.0.0
* Description :unfold:
Introduces a code debugger to Emacs, powered by [[doom-package:][realgud]] or [[doom-package:][dap-mode]] (LSP).
This document will help you to configure [[doom-package:][dap-mode]] [[https://emacs-lsp.github.io/dap-mode/page/configuration/#native-debug-gdblldb][Native Debug(GDB/LLDB)]] as
there is still not *enough* documentation for it.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +lsp ::
Enable support for [[https://microsoft.github.io/debug-adapter-protocol/][Debug Adapter Protocol]] (DAP) debuggers.
** Packages
- [[doom-package:][realgud]]
- [[doom-package:][realgud-trepan-ni]] if [[doom-module:][:lang javascript]]
- if [[doom-module:][+lsp]]
- [[doom-package:][dap-mode]]
- [[doom-package:][posframe]]
** 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
#+begin_quote
🔨 /This module's prerequisites documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
Make sure all of these pre-requirements is in your ~$PATH~:
- =nodejs=
- =lldb= and =lldb-mi= (optional)
- =gdb= (optional), requires =unzip=
If you are getting an error like ~Searching for program no such file or
directory "node"~, then you need [[github:nodejs/node][nodejs]] ([[github:emacs-lsp/dap-mode/issues/79][emacs-lsp/dap-mode#79]]).
** Realgud debuggers
*** lldb and lldb-mi
This is optional if you want to debug with [[https:lldb.llvm.org][LLDB]]. Install lldb and [[github:lldb-tools/lldb-mi][lldb-mi]].
*** gdb
This is optional if you want to debug with [[https:www.gnu.org/software/gdb/][GDB]]. Install gdb.
You will need ~unzip~ for ~dap-gdb-lldb-setup~. It downloads a VS-Code extension
and it needs to extract compressed downloaded file.
You need this if you are having ~"wrong-type-argument stringp nil"~ error when
calling ~dap-gdb-lldb-setup~. [[github:emacs-lsp/dap-mode/issues/313][See emacs-lsp/dap-mode#313]]
** DAP debuggers
*** Python
DAP expects [[https://github.com/Microsoft/ptvsd][ptvsd]] by default as the Python debugger, but [[https://github.com/microsoft/debugpy][debugpy]] is recommended.
See [[*Configuration][Configuration]].
*installing ptvsd:*
#+begin_src sh
pip3 install ptvsd --user
#+end_src
*install debugpy:*
#+begin_src sh
pip3 install debugpy --user
#+end_src
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! dap-mode
(setq dap-python-debugger 'debugpy))
#+end_src
*** C, C++, Rust, Golang
Needs [[https://github.com/llvm/llvm-project/tree/main/lldb/tools/lldb-vscode][lldb-vscode]]. Install LLDB from your package manager.
*Fedora:*
#+begin_src sh
dnf install lldb
#+end_src
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
- ~M-x +debugger/start~
- ~M-x +debugger/start-last~
- ~M-x +debugger/quit~
** Realgud
1. Call ~dap-gdb-lldb-setup~ function.
2. Use ~dap-debug-edit-template~ to configure debugging settings for your
project. [[github:WebFreak001/code-debug/blob/master/package.json#L72][Available settings can be inspected here.]] Call ~eval-buffer~ to save
your settings. *Don't save the file!*
3. Call ~dap-debug~, select a configuration and start debugging.
** dap-mode with ~+lsp~
Intuitive and powerful debugging.
- Breakpoints
- REPL
- *local variable view:* Allows you to browse variables in the current stack
frame.
- *expressions:* Add expressions to either watch variables or generic
expressions.
** Keybindings
#+begin_src emacs-lisp
(map! :map dap-mode-map
:leader
:prefix ("d" . "dap")
;; basics
:desc "dap next" "n" #'dap-next
:desc "dap step in" "i" #'dap-step-in
:desc "dap step out" "o" #'dap-step-out
:desc "dap continue" "c" #'dap-continue
:desc "dap hydra" "h" #'dap-hydra
:desc "dap debug restart" "r" #'dap-debug-restart
:desc "dap debug" "s" #'dap-debug
;; debug
:prefix ("dd" . "Debug")
:desc "dap debug recent" "r" #'dap-debug-recent
:desc "dap debug last" "l" #'dap-debug-last
;; eval
:prefix ("de" . "Eval")
:desc "eval" "e" #'dap-eval
:desc "eval region" "r" #'dap-eval-region
:desc "eval thing at point" "s" #'dap-eval-thing-at-point
:desc "add expression" "a" #'dap-ui-expressions-add
:desc "remove expression" "d" #'dap-ui-expressions-remove
:prefix ("db" . "Breakpoint")
:desc "dap breakpoint toggle" "b" #'dap-breakpoint-toggle
:desc "dap breakpoint condition" "c" #'dap-breakpoint-condition
:desc "dap breakpoint hit count" "h" #'dap-breakpoint-hit-condition
:desc "dap breakpoint log message" "l" #'dap-breakpoint-log-message)
#+end_src
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
- There is a known issue with the ~+debugger/start~ command, which is bound to
[[kbd:][SPC o d]] right now. It prints "No debugging session to quit" no matter what.
* 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

120
modules/tools/direnv/README.org
View file

@ -1,76 +1,98 @@
#+TITLE: tools/direnv
#+DATE: July 10, 2019
#+SINCE: v2.1.0
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools direnv][Issues]] ↖ [[doom-module-source:tools/direnv][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools direnv
#+SUBTITLE: Save (or destroy) the environment at your leisure
#+CREATED: April 05, 2019
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#macos][MacOS]]
- [[#arch-linux][Arch Linux]]
- [[#nixos][NixOS]]
- [[#troubleshooting][Troubleshooting]]
- [[#direnv--nix-is-slow][direnv + nix is slow]]
* Description
* Description :unfold:
This module integrates direnv into Emacs.
#+begin_quote
direnv is an environment switcher for the shell. It knows how to hook into bash,
zsh, tcsh, fish shell and elvish to load or unload environment variables
depending on the current directory. This allows project-specific environment
variables without cluttering the ~/.profile file.
📌 direnv is an environment switcher for the shell. It knows how to hook into
bash, zsh, tcsh, fish shell and elvish to load or unload environment
variables depending on the current directory. This allows project-specific
environment variables without cluttering the ~/.profile file.
Before each prompt, direnv checks for the existence of a ".envrc" file in the
current and parent directories. If the file exists (and is authorized), it is
loaded into a bash sub-shell and all exported variables are then captured by
direnv and then made available to the current shell.
Before each prompt, direnv checks for the existence of a ".envrc" file in
the current and parent directories. If the file exists (and is authorized),
it is loaded into a bash sub-shell and all exported variables are then
captured by direnv and then made available to the current shell.
#+end_quote
** Module Flags
This module provides no flags.
** Maintainers
- [[doom-user:][@hlissner]]
** Plugins
+ [[https://github.com/purcell/envrc][envrc]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][envrc]]
** Hacks
+ Normally, the direnv environment is updated on ~post-command-hook~. We've
changed it to update on ~doom-switch-buffer-hook~, ~doom-switch-window-hook~
and ~doom-switch-frame-hook~ instead.
+ Special direnv keywords/commands are highlighted in direnv-envrc-mode.
+ A fix has been applied to ensure flycheck searches for executables from within
the direnv environment, if any.
- ~envrc-mode~ has been modified to fail gracefully if ~direnv~ isn't available.
- ~envrc-global-mode~ has been modified to activate envrc-mode sooner in the
major mode activation process, so that any env state performed in mode hooks
aren't overwritten by direnv.
- Added direnv support for Org src blocks.
* Prerequisites
This module requires the ~direnv~ utility.
** 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://direnv.net/][direnv]].
** MacOS
#+BEGIN_SRC bash
#+begin_src sh
brew install direnv
#+END_SRC
#+end_src
** Arch Linux
~direnv~ is available on the AUR
#+BEGIN_SRC bash
~direnv~ is available on the AUR:
#+begin_src sh
yay -S direnv
#+END_SRC
#+end_src
** NixOS
#+BEGIN_SRC nix
#+begin_src nix
environment.systemPackages = [ pkgs.direnv ];
#+END_SRC
#+end_src
Or ~nix-env -i direnv~
Or ~$ nix-env -i direnv~
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
To make use of direnv you need a =.envrc= file in a directory. Any time you open
a file or buffer in said directory, the [[doom-package:][envrc]] Emacs package will kick in,
activate the local env, and inject it into Emacs for the current buffer.
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
[[doom-report:][Report an issue?]]
** direnv + nix is slow
Consider augmenting direnv with [[https://github.com/nix-community/lorri][lorri]], which will cache nix builds and speed up
direnv tremendously:
#+BEGIN_SRC nix
#+begin_src nix
services.lorri.enable = true;
#+END_SRC
#+end_src
* 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

185
modules/tools/docker/README.org
View file

@ -1,139 +1,150 @@
#+TITLE: tools/docker
#+DATE: April 30, 2019
#+SINCE: v2.0.9
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools docker][Issues]] ↖ [[doom-module-source:tools/docker][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools docker
#+SUBTITLE: Yo dawg, I heard you like OSes, so I…
#+CREATED: September 06, 2018
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#docker-control][Docker control]]
- [[#supported-commands][Supported commands]]
- [[#tramp][TRAMP]]
- [[#configuration][Configuration]]
- [[#popups][Popups]]
- [[#other-useful-variables][Other useful variables]]
- [[#completion-in-dockerfiles][Completion in Dockerfiles]]
- [[#troubleshooting][Troubleshooting]]
- [[#tramp-hangs-on-alpine-container][Tramp hangs on Alpine container]]
* Description
This module allows you to manipulate Docker images, containers & more from
* Description :unfold:
This module allows you to manipulate Docker images, containers, and more from
Emacs.
Provides a major =dockerfile-mode= to edit =Dockerfiles=. Additional
convenience functions allow images to be built easily.
Provides a major ~dockerfile-mode~ to edit =Dockerfiles=. Additional convenience
functions allow images to be built easily.
=docker-tramp.el= offers a [[https://www.gnu.org/software/tramp/][TRAMP]] method for Docker containers.
[[doom-package:][docker-tramp]] offers [[https://www.gnu.org/software/tramp/][TRAMP]] support for Docker containers.
** Module Flags
+ =+lsp= Enables integration for the Dockerfile Language Server.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/Silex/docker.el][docker]]
+ [[https://github.com/emacs-pe/docker-tramp.el][docker-tramp]]
+ [[https://github.com/spotify/dockerfile-mode][dockerfile-mode]]
** Module flags
- +lsp ::
Enable integration for the Dockerfile Language Server.
* Prerequisites
This module assumes =docker=, =docker-compose= and =docker-machine= binaries
are installed and accessible from your PATH.
** Packages
- [[doom-package:][docker]]
- [[doom-package:][docker-tramp]]
- [[doom-package:][dockerfile-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 assumes =docker=, =docker-compose= and =docker-machine= binaries are
installed and accessible from your PATH.
Optionally, this module also uses the following programs:
- =docker-langserver= (for LSP users): ~$ npm install -g
dockerfile-language-server-nodejs~
+ =docker-langserver= (for LSP users): ~npm install -g dockerfile-language-server-nodejs~
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
** Docker control
Use =M-x docker=, select a resource, and then mark or unmark items using the
Use ~M-x docker~, select a resource, and then mark or unmark items using the
following keybindings (for more marking possibilities, check out
https://github.com/politza/tablist):
[[github:politza/tablist][politza/tablist]]):
| Binding | Description |
|-----------+----------------------|
| =?= | List actions |
| =l= | Configure listing |
| =m= | Mark item |
| =u= | Unmark item |
| =t= | Toggle marks |
| =U= | Unmark all |
| =s= | Sort |
| =* r= | Mark items by regexp |
| =<= | Shrink column |
| =>= | Enlarge column |
| =C-c C-e= | Export to csv |
| [[kbd:][?]] | List actions |
| [[kbd:][l]] | Configure listing |
| [[kbd:][m]] | Mark item |
| [[kbd:][u]] | Unmark item |
| [[kbd:][t]] | Toggle marks |
| [[kbd:][U]] | Unmark all |
| [[kbd:][s]] | Sort |
| [[kbd:][* r]] | Mark items by regexp |
| [[kbd:][<]] | Shrink column |
| [[kbd:][>]] | Enlarge column |
| [[kbd:][C-c C-e]] | Export to csv |
*** Supported commands
- =docker container=: =attach=, =cp=, =diff=, =inspect=, =kill=, =logs=,
=pause=, =rename=, =restart=, =rm=, =start=, =stop=, =unpause=
- =docker image=: =inspect=, =pull=, =push=, =rm=, =run=, =tag=
- =docker network=: =rm=
- =docker volume=: =rm=
- =docker-machine=: =create=, =env=, =restart=, =rm=, =start=, =stop=
- =docker-compose=: =build=, =config=, =create=, =down=, =exec=, =logs=,
=pull=, =push=, =remove=, =restart=, =run=, =start=, =stop=, =up=
- ~docker container~: ~attach~, ~cp~, ~diff~, ~inspect~, ~kill~, ~logs~,
~pause~, ~rename~, ~restart~, ~rm~, ~start~, ~stop~, ~unpause~
- ~docker image~: ~inspect~, ~pull~, ~push~, ~rm~, ~run~, ~tag~
- ~docker network~: ~rm~
- ~docker volume~: ~rm~
- ~docker-machine~: ~create~, ~env~, ~restart~, ~rm~, ~start~, ~stop~
- ~docker-compose~: ~build~, ~config~, ~create~, ~down~, ~exec~, ~logs~, ~pull~,
~push~, ~remove~, ~restart~, ~run~, ~start~, ~stop~, ~up~
You can also enter =dired= or open a file inside a container or volume.
** TRAMP
Offers the [[https://www.gnu.org/software/tramp/][TRAMP]] method =docker= to access running containers.
Offers the [[https://www.gnu.org/software/tramp/][TRAMP]] method =docker= to access running containers:
#+BEGIN_EXAMPLE
C-x C-f /docker:user@container:/path/to/file
C-x C-f /docker:$USER@$CONTAINER:/path/to/file
#+END_EXAMPLE
| =user= | the user that you want to use (optional) |
| =container= | the id or name of the container |
| =$USER= | the user that you want to use (optional) |
| =$CONTAINER= | the id or name of the container |
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Popups
Thanks to [[https://github.com/magit/magit-popup][magit-popup]], all the popups default arguments can be customized. For
example, here is how to customize the arguments for =docker-image-run-popup=:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(setq docker-image-run-arguments '("-i" "-t" "--rm"))
#+END_SRC
#+end_src
or inside a =use-package= declaration:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(use-package! docker
:bind ("C-c d" . docker)
:custom (docker-image-run-arguments '("-i" "-t" "--rm")))
#+END_SRC
You can also customize these using =M-x customize-variable=.
#+end_src
*** Other useful variables
| Variable | Description | Default |
|-------------------------------------+---------------------------------------+------------------|
| =docker-command= | The docker binary to use | =docker= |
| =docker-container-default-sort-key= | Sort key for docker containers | =("Image")= |
| =docker-container-shell-file-name= | Shell to use when entering containers | =/bin/bash= |
| =docker-image-default-sort-key= | Sort key for docker images | =("Repository")= |
| =docker-machine-default-sort-key= | Sort key for docker machines | =("Name")= |
| =docker-network-default-sort-key= | Sort key for docker networks | =("Name")= |
| =docker-run-as-root= | Run docker as root | =nil= |
| =docker-volume-default-sort-key= | Sort key for docker volumes | =("Driver")= |
| ~docker-command~ | The docker binary to use | ~docker~ |
| ~docker-container-default-sort-key~ | Sort key for docker containers | ~("Image")~ |
| ~docker-container-shell-file-name~ | Shell to use when entering containers | ~/bin/bash~ |
| ~docker-image-default-sort-key~ | Sort key for docker images | ~("Repository")~ |
| ~docker-machine-default-sort-key~ | Sort key for docker machines | ~("Name")~ |
| ~docker-network-default-sort-key~ | Sort key for docker networks | ~("Name")~ |
| ~docker-run-as-root~ | Run docker as root | ~nil~ |
| ~docker-volume-default-sort-key~ | Sort key for docker volumes | ~("Driver")~ |
** Completion in Dockerfiles
By default, the keyword completion function detects the =docker-compose=
version of the current buffer and suggests the appropriate keywords.
By default, the keyword completion function detects the =docker-compose= version
of the current buffer and suggests the appropriate keywords.
You can change the candidates offered by the backend by customizing
=docker-compose-keywords=.
* Troubleshooting
[[doom-report:][Report an issue?]]
** Tramp hangs on Alpine container
Busyboxes built with the =ENABLE_FEATURE_EDITING_ASK_TERMINAL= config option
also send escape sequences, which =tramp-wait-for-output= doesn't ignore
correctly. This was [[http://git.savannah.gnu.org/cgit/tramp.git/commit/?id=98a511248a9405848ed44de48a565b0b725af82c][fixed in TRAMP upstream]] and is available since TRAMP 2.3.
For older versions of TRAMP you can dump [[https://github.com/emacs-pe/docker-tramp.el/blob/master/docker-tramp-compat.el][docker-tramp-compat.el]] in your
=load-path= somewhere and add the following to your =init.el= to overwrite
=tramp-wait-for-output= with the patch applied:
~load-path~ somewhere and add the following to =$DOOMDIR/config.el= to overwrite
~tramp-wait-for-output~ with the patch applied:
#+begin_src emacs-lisp
(after! tramp
(require 'docker-tramp-compat))
#+end_src
#+BEGIN_SRC emacs-lisp
(require 'docker-tramp-compat)
#+END_SRC
* 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

89
modules/tools/editorconfig/README.org
View file

@ -1,46 +1,44 @@
#+TITLE: tools/editorconfig
#+DATE: August 22, 2020
#+SINCE: 2.0.9
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools editorconfig][Issues]] ↖ [[doom-module-source:tools/editorconfig][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools editorconfig
#+SUBTITLE: Let someone else argue tabs and spaces
#+CREATED: December 27, 2015
#+SINCE: 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]]
- [[#adding-support-for-more-major-modes][Adding support for more major modes]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module integrates [[https://editorconfig.org/][EditorConfig]] into Emacs, allowing users to dictate code
style on a per-project basis with an =.editorconfig= file ([[https://editorconfig-specification.readthedocs.io/][formal
specification]]).
** 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/editorconfig/editorconfig-emacs][editorconfig-emacs]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][editorconfig-emacs]]
** Hacks
+ Added logic to guess an extension-less file's type from its shebang line. For
- Added logic to guess an extension-less file's type from its shebang line. For
example, editorconfig rules for =*.py= files will apply to =bin/myscript=
assuming its first line is ~#!/usr/bin/env python~. See
~+editorconfig-mode-alist~ for adding support for more languages.
+ *Special integration for =dtrt-indent=:* If the local editorconfig file
specifies ~indent_style~ or ~indent_size~, the =dtrt-indent= (which tries to
- *Special integration for =dtrt-indent=:* If the local editorconfig file
specifies ~indent_style~ or ~indent_size~, the [[doom-package:][dtrt-indent]] (which tries to
guess your indent settings by analyzing your text file) will bow out.
+ *Special integration for =ws-butler=:* this module will use =ws-butler= to
- *Special integration for =ws-butler=:* this module will use [[doom-package:][ws-butler]] to
enforce ~trim_trailing_whitespace~.
* 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 one optional dependency: the ~editorconfig~ native binary.
Without it, a built-in elisp implementation will be used, but it has fewer
features and can be a bit slower.
@ -48,11 +46,15 @@ features and can be a bit slower.
The editorconfig binary has [[https://github.com/editorconfig#contributing][many implementations]] you can choose from, typically
available through your OS package manager (or build it yourself).
* Features
* Usage
You will need to write an ~.editorconfig~ file in your project (this is usually
in the root of your project) you can find out about all the properties [[https://editorconfig.org/#example-file][here]]
in the root of your project) you can find out about all the properties [[https://editorconfig.org/#example-file][here]].
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Configuration
** Adding support for more major modes
Out the box, the editorconfig plugin supports many Emacs major modes, but it's
possible you'll find one it doesn't support. Adding support is easy so long as
@ -63,16 +65,25 @@ doesn't:
The ~editorconfig-indentation-alist~ variable contains a list of major modes and
their indentation variables. To add coffee-mode to it:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! editorconfig
(add-to-list 'editorconfig-indentation-alist '(coffee-mode coffee-tab-width)))
#+END_SRC
#+end_src
But what if you don't know the correct indentation variable(s). Use =SPC h v=
(=C-h v= for non-evil users) to peruse all the available variables in your
current session of Emacs. Look for variables that have the words =indent=,
=offset= or =tab-width= in them. They will be prefixed with the plugin they
belong to (e.g. ~rustic-indent-offset~).
But what if you don't know the correct indentation variable(s). Use [[kbd:][SPC h v]] ([[kbd:][C-h
v]] for non-evil users) to peruse all the available variables in your current
session of Emacs. Look for variables that have the words =indent=, =offset= or
=tab-width= in them. They will be prefixed with the plugin they belong to (e.g.
~rustic-indent-offset~).
* 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

69
modules/tools/ein/README.org
View file

@ -1,26 +1,55 @@
#+TITLE: tools/ein
#+DATE: April 11, 2018
#+SINCE: v2.0
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools ein][Issues]] ↖ [[doom-module-source:tools/ein][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools ein
#+SUBTITLE: Tame Jupyter notebooks with emacs
#+CREATED: April 11, 2018
#+SINCE: 21.12.0 (#524)
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
* Description :unfold:
Adds [[https://jupyter.org/][Jupyter]] notebook integration into Emacs.
* Description
Adds Jupyter notebook integration into emacs.
** 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/millejoh/emacs-ipython-notebook][ein]]
** Packages
- [[doom-package:][ein]]
* Prerequisites
This module has no prerequisites.
** Hacks
/No hacks documented for this module./
* Features
Please refer [[https://github.com/millejoh/emacs-ipython-notebook][millejoh/emacs-ipython-notebook's README]].
** 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's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Refer to [[https://github.com/millejoh/emacs-ipython-notebook][millejoh/emacs-ipython-notebook's README]].
* 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

125
modules/tools/eval/README.org
View file

@ -1,73 +1,79 @@
#+TITLE: tools/eval
#+DATE: February 13, 2017
#+SINCE: v2.0
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools eval][Issues]] ↖ [[doom-module-source:tools/eval][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools eval
#+SUBTITLE: Run code, run (also, repls)
#+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]]
- [[#inline-code-evaluation][Inline Code Evaluation]]
- [[#repls][REPLs]]
- [[#configuration][Configuration]]
- [[#register-a-repl-for-a-major-mode][Register a REPL for a major-mode]]
- [[#change-how-code-is-evaluated-in-a-major-mode][Change how code is evaluated in a major mode]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This modules adds inline code evaluation support to Emacs and a universal
interface for opening and interacting with REPLs.
** Module Flags
+ =+overlay= Enables the use of overlays (near the cursor) to display the result
of inline code evaluation (rather than the minibuffer). That is, unless the
results are too big, in which case it will still fall back to popup buffers.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/syohex/emacs-quickrun][quickrun]]
** Module flags
- +overlay ::
Enable the use of overlays (near the cursor) to display the result of inline
code evaluation (rather than the minibuffer). If the results are too big the
minibuffer will be used anyway.
** Packages
- [[doom-package:][quickrun]]
** Hacks
+ Quickrun has been modified to:
+ Use only one output window, in case of consecutive execution of code.
+ The quickrun window will resize itself to fit its output, once the
- Quickrun has been modified to:
- Use only one output window, in case of consecutive execution of code.
- The quickrun window will resize itself to fit its output, once the
underlying process is finished executing the code.
* 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 direct prerequisites.
However, many languages will require that you install their interpreters, code
runners and/or repls to power the functionality of this module. Visit the
documentation of their respective =:lang= module for instructions.
documentation of their respective [[doom-module:][:lang]] module for instructions.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
* Features
** Inline Code Evaluation
Quickrun can be invoked via:
+ ~M-x +eval/buffer~ (or ~gR~, or ~M-r~)
+ ~M-x +eval/region~
+ ~M-x +eval/region-and-replace~
+ Evil users can use the ~gr~ operator to select and run a region.
- ~M-x +eval/buffer~ (or [[kbd:][gR]], or [[kbd:][M-r]])
- ~M-x +eval/region~
- ~M-x +eval/region-and-replace~
- Evil users can use the [[kbd:][gr]] operator to select and run a region.
** REPLs
Invoked via:
+ =SPC o r= or ~:repl~ will open a REPL in a popup window. =SPC o R= or ~:repl!~
- [[kbd:][SPC o r]] or ~:repl~ will open a REPL in a popup window. [[kbd:][SPC o R]] or ~:repl!~
will open a REPL in the current window. If a REPL is already open and a
selection is active, it will be sent to the REPL.
+ ~M-x +eval/open-repl-other-window~ (=SPC o r=)
+ ~M-x +eval/open-repl-same-window~ (=SPC o R=)
+ ~M-x +eval/send-region-to-repl~ (=SPC c s=) while a selection (and REPL) is
- ~M-x +eval/open-repl-other-window~ ([[kbd:][SPC o r]])
- ~M-x +eval/open-repl-same-window~ ([[kbd:][SPC o R]])
- ~M-x +eval/send-region-to-repl~ ([[kbd:][SPC c s]]) while a selection (and REPL) is
active
* Configuration
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Register a REPL for a major-mode
REPLs are defined for most languages Doom supports. Check that language module's
README.org to see if it does (and if it requires additional setup).
To use them, you may use ~M-x +eval/open-repl-other-window~, ~M-x
+eval/open-repl-same-window~, ~:repl~ (for evil users) or the default binding:
=SPC o r=. These will open a REPL in a popup window.
[[kbd:][SPC o r]]. These will open a REPL in a popup window.
#+begin_quote
You can simply call that mode's REPL command manually. e.g. ~M-x ielm~, but this
@ -79,19 +85,18 @@ Otherwise, you can define your own for a specified major mode:
~(set-repl-handler! MAJOR-MODES FUNCTION)~
MAJOR-MODES is a single major mode symbol or a list of them.
=MAJOR-MODES= is a single major mode symbol or a list of them.
FUNCTION should return a repl buffer. Any window changes in this function are
ignored, then the REPL is opened in a popup window.
#+BEGIN_SRC emacs-lisp
=FUNCTION= should return a repl buffer. Any window changes in this function are
ignored, then the REPL is opened in a popup window. E.g.
#+begin_src emacs-lisp
(defun +lua/open-repl ()
(interactive)
(lua-start-process "lua" "lua")
(pop-to-buffer lua-process-buffer))
(set-repl-handler! 'lua-mode #'+lua/open-repl)
#+END_SRC
#+end_src
** Change how code is evaluated in a major mode
Run regions or entire buffers with [[https://github.com/syohex/emacs-quickrun][Quickrun]]. Output is show in a popup window.
@ -101,25 +106,31 @@ to interpreters or compilers. However, occasionally, you'll find a language
without support (like [[https://crystal-lang.org/][Crystal]]), or a language with better Emacs integration
(like elisp).
Here's how you define a "runner":
#+BEGIN_SRC emacs-lisp
To define a "runner":
#+begin_src emacs-lisp
(set-eval-handler! 'crystal-mode
'((:command . "crystal")
(:exec . "%c %s")
(:description . "Run Crystal script")))
#+END_SRC
#+end_src
A simpler version is simply to use the path to the binary:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(set-eval-handler! 'groovy-mode "groovy")
#+END_SRC
#+end_src
Or if you'd rather run an elisp command:
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(set-eval-handler! 'emacs-lisp-mode #'+emacs-lisp-eval)
#+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

57
modules/tools/gist/README.org Normal file
View file

@ -0,0 +1,57 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools gist][Issues]] ↖ [[doom-module-source:tools/gist][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools gist
#+SUBTITLE: A pastebin for Githubsters
#+CREATED: May 07, 2017
#+SINCE: 2.0.3
#+begin_quote
🚧 *This module is deprecated.* gist.el has been abandoned and is generally
buggy. This may be replaced by a more general pastebin module that
interfaces with various pastebin servers.
#+end_quote
* Description :unfold:
Adds the ability to manage, pull from, or push to your [[https://gist.github.com][Gists]] from within Emacs.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][gist]]
** 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

232
modules/tools/lookup/README.org
View file

@ -1,74 +1,73 @@
#+TITLE: tools/lookup
#+DATE: January 4, 2018
#+SINCE: v2.0.9
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools lookup][Issues]] ↖ [[doom-module-source:tools/lookup][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools lookup
#+SUBTITLE: Navigate your labyrinthine code and docs
#+CREATED: January 04, 2018
#+SINCE: 2.0.9
* Table of Contents :TOC:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#macos][MacOS]]
- [[#arch-linux][Arch Linux]]
- [[#nixos][NixOS]]
- [[#features][Features]]
- [[#jump-to-definition][Jump to definition]]
- [[#find-references][Find references]]
- [[#look-up-documentation][Look up documentation]]
- [[#search-a-specific-documentation-backend][Search a specific documentation backend]]
- [[#dashapp-docset-integration][Dash.app Docset integration]]
- [[#configuration][Configuration]]
- [[#associating-lookup-handlers-with-major-modes][Associating lookup handlers with major modes]]
- [[#associating-dash-docsets-with-major-modes][Associating Dash docsets with major modes]]
- [[#open-in-eww-instead-of-browser][Open in eww instead of browser]]
- [[#open-in-xwidget-webkit-instead-of-browser][Open in Xwidget WebKit instead of browser]]
- [[#appendix][Appendix]]
- [[#commands][Commands]]
* Description
* Description :unfold:
This module adds code navigation and documentation lookup tools to help you
quickly look up definitions, references, documentation, dictionary definitions
or synonyms.
+ Jump-to-definition and find-references implementations that just work.
+ Powerful xref integration for languages that support it.
+ Search online providers like devdocs.io, stackoverflow, google, duckduckgo or
youtube (duckduckgo and google have live suggestions).
+ Integration with Dash.app docsets.
+ Support for online (and offline) dictionaries and thesauruses.
- Jump-to-definition and find-references implementations that just work.
- Powerful xref integration for languages that support it.
- Search online providers like [[https://devdocs.io][devdocs.io]], [[https://stackoverflow.com][stackoverflow]], [[https://google.com][google]], [[https://duckduckgo.com][duckduckgo]], or
[[https://youtube.com][youtube]] (duckduckgo and google have live suggestions).
- Integration with [[https://github.com/Kapeli/feeds][Dash.app docsets]].
- Support for online (and offline) dictionaries and thesauruses.
** Module Flags
+ ~+dictionary~ Enable word definition and thesaurus lookup functionality.
+ ~+offline~ Install and prefer offline dictionary/thesaurus.
+ ~+docsets~ Enable integration with Dash.app docsets.
** Maintainers
- [[doom-user:][@hlissner]]
** Plugins
+ [[https://github.com/jacktasia/dumb-jump][dumb-jump]]
+ [[https://github.com/alexmurray/ivy-xref][ivy-xref]] or [[https://github.com/brotzeit/helm-xref][helm-xref]]
+ [[https://github.com/tkf/emacs-request][request]]
+ =+docsets=
+ [[https://github.com/dash-docs-el/dash-docs][dash-docs]]
+ [[https://github.com/nathankot/counsel-dash][counsel-dash]] or [[https://github.com/areina/helm-dash][helm-dash]]
+ =+dictionary=
+ if macOS
+ [[https://github.com/xuchunyang/osx-dictionary.el][osx-dictionary]]* (on macOS)
+ else
+ [[https://github.com/abo-abo/define-word][define-word]]
+ [[https://github.com/maxchaos/emacs-powerthesaurus][powerthesaurus]]
+ =+offline=
+ [[https://github.com/gromnitsky/wordnut][wordnut]]
+ [[https://github.com/hpdeifel/synosaurus][synosaurus]]
[[doom-contrib-maintainer:][Become a maintainer?]]
* Prerequisites
This module has several soft dependencies:
** Module flags
- +dictionary ::
Enable word definition and thesaurus lookup functionality.
- +docsets ::
Enable integration with Dash.app docsets.
- +offline ::
Install and prefer offline dictionary/thesaurus (with [[doom-module:][+dictionary]]).
+ ~ripgrep~ as a last-resort fallback for jump-to-definition/find-references.
+ ~sqlite3~ for Dash docset support (if you have =+docsets= enabled)
+ ~wordnet~ for offline dictionary and thesaurus support (if you have
=+dictionary +offline= enabled).
** Packages
- [[doom-package:][dumb-jump]]
- [[doom-package:][helm-xref]] if [[doom-module:][:completion helm]]
- [[doom-package:][ivy-xref]] if [[doom-module:][:completion ivy]]
- [[doom-package:][request]]
- if [[doom-module:][+docsets]]
- [[doom-package:][dash-docs]]
- [[doom-package:][counsel-dash]] if [[doom-module:][:completion ivy]]
- [[doom-package:][helm-dash]] if [[doom-module:][:completion helm]]
- if [[doom-module:][+dictionary]]
- if macOS
- [[doom-package:][osx-dictionary]]
- else
- [[doom-package:][define-word]]
- [[doom-package:][powerthesaurus]]
- if [[doom-module:][+offline]]
- [[doom-package:][wordnut]]
- [[doom-package:][synosaurus]]
** 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 several optional dependencies:
- ~ripgrep~ as a last-resort fallback for jump-to-definition/find-references.
- ~sqlite3~ for Dash docset support (if you have [[doom-module:][+docsets]] enabled)
- ~wordnet~ for offline dictionary and thesaurus support (if you have
[[doom-module:][+dictionary]] and [[doom-module:][+offline]] enabled).
** MacOS
#+BEGIN_SRC sh
#+begin_src sh
brew install ripgrep wordnet
# An older version of sqlite is included in MacOS. If it causes you problems (and
@ -77,27 +76,27 @@ brew install sqlite
# Note that it's keg-only, meaning it isn't symlinked to /usr/local/bin. You'll
# have to add it to PATH yourself (or symlink it into your PATH somewhere). e.g.
export PATH="/usr/local/opt/sqlite/bin:$PATH"
#+END_SRC
#+end_src
** Arch Linux
#+BEGIN_SRC sh
#+begin_src sh
sudo pacman -S sqlite ripgrep
yay -S wordnet-cli
#+END_SRC
#+end_src
** NixOS
#+BEGIN_SRC nix
#+begin_src nix
environment.systemPackages = with pkgs; [
ripgrep
sqlite
wordnet
];
#+END_SRC
#+end_src
* Features
* Usage
** Jump to definition
Use ~+lookup/definition~ (bound to =gd= in normal mode) to jump to the
definition of the symbol at point
Use ~+lookup/definition~ (bound to [[kbd:][gd]] in normal mode) to jump to the definition
of the symbol at point.
This module provides a goto-definition implementation that will try the
following sources before giving up:
@ -105,30 +104,30 @@ following sources before giving up:
1. Whatever ~:definition~ function is registered for the current buffer with the
~:lookup~ setting (see "Configuration" section).
2. Any available xref backends.
3. ~dumb-jump~ (a text search with aides to reduce false positives).
3. An ordinary project-wide text search with ripgrep.
3. [[doom-package:][dumb-jump]] (a text search with aides to reduce false positives).
3. An ordinary project-wide text search with =ripgrep=.
5. If ~evil-mode~ is active, use ~evil-goto-definition~, which preforms a simple
text search within the current buffer.
If there are multiple results, you will be prompted to select one.
** Find references
Use ~+lookup/references~ (bound to =gD= in normal mode) to see a list of
Use ~+lookup/references~ (bound to [[kbd:][gD]] in normal mode) to see a list of
references for the symbol at point from throughout your project.
Like ~+lookup/definition~, this tries a number of sources before giving up. It
will try:
1. Whatever ~:references~ function is registered for the current buffer with the
~:lookup~ setting (see "Configuration" section).
2. Any available xref backends.
~:lookup~ setting (see [[*Configuration][Configuration]]).
2. Any available [[doom-package:][xref]] backends.
3. An ordinary project-wide text search with ripgrep.
If there are multiple results, you will be prompted to select one.
** Look up documentation
~+lookup/documentation~ (bound to =K= in normal mode) will open documentation
for the symbol at point.
~+lookup/documentation~ (bound to [[kbd:][K]] in normal mode) will open documentation for
the symbol at point.
Depending on your configuration, this will try a list of sources:
@ -143,8 +142,8 @@ Depending on your configuration, this will try a list of sources:
You can perform a documentation lookup on any backends directly:
+ Dash Docsets: ~+lookup/in-docsets~, or ~:dash QUERY~ for evil users.
+ Online (generic): ~+lookup/online~ or ~+lookup/online-select~ (bound to =SPC /
o=), or ~:lo[okup] QUERY~ for evil users.
+ Online (generic): ~+lookup/online~ or ~+lookup/online-select~ (bound to [[kbd:][SPC /
o]]), or ~:lo[okup] QUERY~ for evil users.
** Dash.app Docset integration
You can install dash docsets with ~M-x dash-docset-install-docset~ and search
@ -153,26 +152,31 @@ modes that don't have a specialized :documentation lookup handler.
* Configuration
** Associating lookup handlers with major modes
~set-lookup-handlers! MODES &key DEFINITION REFERENCES DOCUMENTATION FILE XREF-BACKEND ASYNC~
~set-lookup-handlers! MODES &key DEFINITION REFERENCES DOCUMENTATION FILE
XREF-BACKEND ASYNC~
Use ~set-lookup-handlers!~ to register lookup targets for MODES (a major or
minor mode symbol or list thereof). PLIST accepts the following optional
properties:
+ ~:definition FN~ :: Run when jumping to a symbol's definition. Used by
~+lookup/definition~.
+ ~:references FN~ :: Run when looking for usage references of a symbol in the
current project. Used by ~+lookup/references~.
+ ~:documentation FN~ :: Run when looking up documentation for a symbol. Used by
- ~:definition FN~ ::
Run when jumping to a symbol's definition. Used by ~+lookup/definition~.
- ~:references FN~ ::
Run when looking for usage references of a symbol in the current project. Used
by ~+lookup/references~.
- ~:documentation FN~ ::
Run when looking up documentation for a symbol. Used by
~+lookup/documentation~.
+ ~:file FN~ :: Run when looking up the file for a symbol/string. Typically a
file path. Used by ~+lookup/file~.
+ ~:xref-backend FN~ :: Defines an xref backend, which implicitly provides
:definition and :references handlers. If you specify them anyway, they will
take precedence over the xref backend, however.
- ~:file FN~ ::
Run when looking up the file for a symbol/string. Typically a file path. Used
by ~+lookup/file~.
- ~:xref-backend FN~ ::
Defines an [[doom-package:][xref]] backend, which implicitly provides ~:definition~ and
~:references~ handlers. If you specify them anyway, they will take precedence
over the xref backend, however.
e.g.
#+BEGIN_SRC emacs-lisp
E.g.
#+begin_src emacs-lisp
;; For python-mode, anaconda-mode offers a backend for all three lookup
;; functions. We can register them like so:
(set-lookup-handlers! 'python-mode
@ -185,7 +189,7 @@ e.g.
;; experience. You can specify custom xref backends with:
(set-lookup-handlers! 'js2-mode :xref-backend #'xref-js2-xref-backend)
;; NOTE: xref doesn't provide a :documentation backend.
#+END_SRC
#+end_src
** Associating Dash docsets with major modes
~set-docsets! MODES &rest DOCSETS...~
@ -194,14 +198,14 @@ Use ~set-docsets!~ to register DOCSETS (one string or list of strings) for MODES
(one major mode symbol or a list of them). It is used by ~+lookup/in-docsets~
and ~+lookup/documentation~.
e.g.
#+BEGIN_SRC emacs-lisp
E.g.
#+begin_src emacs-lisp
(set-docsets! 'js2-mode "JavaScript" "JQuery")
;; Add docsets to minor modes by starting DOCSETS with :add
(set-docsets! 'rjsx-mode :add "React")
;; Or remove docsets from minor modes
(set-docsets! 'nodejs-mode :remove "JQuery")
#+END_SRC
#+end_src
This determines what docsets to implicitly search for when you use
~+lookup/documentation~ in a mode with no ~:documentation~ handler. Those
@ -211,14 +215,13 @@ docsets must be installed with ~dash-docset-install-docset~.
~+lookup/online~ opens the search results with in ~+lookup-open-url-fn~
(default: ~#'browse-url~). Here is how to change this to EWW (so it opens inside
Emacs):
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(setq +lookup-open-url-fn #'eww)
#+END_SRC
#+end_src
#+begin_quote
~+lookup/in-docsets~ consults ~dash-docs-browser-func~ instead, which is already
set to ~#'eww~ by default.
📌 ~+lookup/in-docsets~ consults ~dash-docs-browser-func~ instead, which is
already set to ~#'eww~ by default.
#+end_quote
** Open in Xwidget WebKit instead of browser
@ -226,19 +229,28 @@ To open results from ~+lookup/online~ or ~+lookup/in-docsets~ in Xwidget WebKit
instead of your system browser, set ~+lookup-open-url-fn~ and/or
~dash-docs-browser-func~ to ~+lookup-xwidget-webkit-open-url-fn~ (needs Emacs
with Xwidgets support):
#+BEGIN_SRC emacs-lisp
#+begin_src emacs-lisp
(setq +lookup-open-url-fn #'+lookup-xwidget-webkit-open-url-fn)
(after! dash-docs
(setq dash-docs-browser-func #'+lookup-xwidget-webkit-open-url-fn))
#+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's appendix is incomplete./ [[doom-contrib-module:][Write more?]]
#+end_quote
* Appendix
** Commands
+ ~+lookup/definition~
+ ~+lookup/references~
+ ~+lookup/documentation~
+ ~+lookup/online~
+ ~+lookup/online-select~
+ ~+lookup/in-devdocs~
+ ~+lookup/in-docsets~
- ~+lookup/definition~
- ~+lookup/references~
- ~+lookup/documentation~
- ~+lookup/online~
- ~+lookup/online-select~
- ~+lookup/in-devdocs~
- ~+lookup/in-docsets~

180
modules/tools/lsp/README.org
View file

@ -1,81 +1,77 @@
#+TITLE: tools/lsp
#+DATE: March 05, 2019
#+SINCE: v2.1
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools lsp][Issues]] ↖ [[doom-module-source:tools/lsp][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools lsp
#+SUBTITLE: M-x vscode
#+CREATED: March 05, 2019
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#lsp-powered-project-search][LSP-powered project search]]
- [[#differences-between-eglot-and-lsp-mode][Differences between eglot and lsp-mode]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
- [[#my-language-server-is-not-found][My language server is not found]]
- [[#lspeglot-is-not-started-automatically-in-my-buffer][LSP/Eglot is not started automatically in my buffer]]
* Description
* Description :unfold:
This module integrates [[https://langserver.org/][language servers]] into Doom Emacs. They provide features
you'd expect from IDEs, like code completion, realtime linting, language-aware
imenu/xref integration, jump-to-definition/references support, and more.
To get LSP working, you'll need to do three things:
1. Enable this module,
2. Install a language server appropriate for your targeted language(s) (you'll
find a table mapping languages to available servers [[https://github.com/emacs-lsp/lsp-mode#supported-languages][in the lsp-mode project
README]]).
3. Enable the =+lsp= flag on the =:lang= modules you want to enable LSP support
for. If your language's module doesn't have LSP support, and you know it can
(or should), please let us know! In the meantime, you must configure it
yourself (described in the Configuration section).
[[doom-package:][imenu]]/[[doom-package:][xref]] integration, jump-to-definition/references support, and more.
As of this writing, this is the state of LSP support in Doom Emacs:
| Module | Major modes | Default language server |
|------------------+---------------------------------------------------------+---------------------------------------------------------------|
| [[../../lang/cc/README.org][:lang cc]] | c-mode, c++-mode, objc-mode | ccls |
| [[../../lang/clojure/README.org][:lang clojure]] | clojure-mode | clojure-lsp |
| [[../../lang/csharp/README.org][:lang csharp]] | csharp-mode | omnisharp |
| [[../../lang/elixir/README.org][:lang elixir]] | elixir-mode | elixir-ls |
| [[../../lang/fsharp/README.org][:lang fsharp]] | fsharp-mode | Mono, .NET core |
| [[../../lang/go/README.org][:lang go]] | go-mode | go-langserver |
| [[../../lang/haskell/README.org][:lang haskell]] | haskell-mode | haskell-language-server |
| [[../../lang/java/README.org][:lang java]] | java-mode | lsp-java |
| [[../../lang/javascript/README.org][:lang javascript]] | js2-mode, rjsx-mode, typescript-mode | typescript-language-server |
| [[../../lang/julia/README.org][:lang julia]] | julia-mode | LanguageServer.jl |
| [[../../lang/ocaml/README.org][:lang ocaml]] | tuareg-mode | ocaml-language-server |
| [[../../lang/php/README.org][:lang php]] | php-mode | php-language-server |
| [[../../lang/python/README.org][:lang python]] | python-mode | lsp-python-ms |
| [[../../lang/ruby/README.org][:lang ruby]] | ruby-mode | solargraph |
| [[../../lang/rust/README.org][:lang rust]] | rust-mode | rls |
| [[../../lang/scala/README.org][:lang scala]] | scala-mode | metals |
| [[../../lang/sh/README.org][:lang sh]] | sh-mode | bash-language-server |
| [[../../lang/swift/README.org][:lang swift]] | swift-mode | sourcekit |
| [[../../lang/web/README.org][:lang web]] | web-mode, css-mode, scss-mode, sass-mode, less-css-mode | vscode-css-languageserver-bin, vscode-html-languageserver-bin |
| [[../../lang/purescript/README.org][:lang purescript]] | purescript-mode | purescript-language-server |
| [[../../lang/zig/README.org][:lang zig]] | zig-mode | zls |
| [[doom-module:][:lang cc]] | c-mode, c++-mode, objc-mode | ccls, clangd |
| [[doom-module:][:lang clojure]] | clojure-mode | clojure-lsp |
| [[doom-module:][:lang csharp]] | csharp-mode | omnisharp |
| [[doom-module:][:lang elixir]] | elixir-mode | elixir-ls |
| [[doom-module:][:lang fsharp]] | fsharp-mode | Mono, .NET core |
| [[doom-module:][:lang go]] | go-mode | go-langserver |
| [[doom-module:][:lang haskell]] | haskell-mode | haskell-language-server |
| [[doom-module:][:lang java]] | java-mode | lsp-java |
| [[doom-module:][:lang javascript]] | js2-mode, rjsx-mode, typescript-mode | ts-ls, deno-ls |
| [[doom-module:][:lang julia]] | julia-mode | LanguageServer.jl |
| [[doom-module:][:lang ocaml]] | tuareg-mode | ocaml-language-server |
| [[doom-module:][:lang php]] | php-mode | php-language-server |
| [[doom-module:][:lang purescript]] | purescript-mode | purescript-language-server |
| [[doom-module:][:lang python]] | python-mode | lsp-python-ms |
| [[doom-module:][:lang ruby]] | ruby-mode | solargraph |
| [[doom-module:][:lang rust]] | rust-mode | rls |
| [[doom-module:][:lang scala]] | scala-mode | metals |
| [[doom-module:][:lang sh]] | sh-mode | bash-language-server |
| [[doom-module:][:lang swift]] | swift-mode | sourcekit |
| [[doom-module:][:lang web]] | web-mode, css-mode, scss-mode, sass-mode, less-css-mode | vscode-css-languageserver-bin, vscode-html-languageserver-bin |
| [[doom-module:][:lang zig]] | zig-mode | zls |
** Module Flags
+ =+peek= Use =lsp-ui-peek= when looking up definitions and references with
functionality from the =:tools lookup= module.
+ =+eglot= Use [[https://elpa.gnu.org/packages/eglot.html][Eglot]] instead of [[https://github.com/emacs-lsp/lsp-mode][LSP-mode]] to implement the LSP client in
Emacs.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/emacs-lsp/lsp-mode][lsp-mode]]
+ [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]]
+ [[https://github.com/emacs-lsp/lsp-ivy][lsp-ivy]] (=:completion ivy=)
+ [[https://github.com/emacs-lsp/helm-lsp][helm-lsp]] (=:completion helm=)
+ [[https://github.com/gagbo/consult-lsp][consult-lsp]] (=:completion vertico=)
+ [[https://github.com/joaotavora/eglot][eglot]]
** Module flags
- +eglot ::
Use [[https://elpa.gnu.org/packages/eglot.html][Eglot]] instead of [[https://github.com/emacs-lsp/lsp-mode][LSP-mode]] to implement the LSP client in Emacs.
- +peek ::
Use ~lsp-ui-peek~ when looking up definitions and references with
functionality from the [[doom-module:][:tools lookup]] module.
* Prerequisites
This module has no direct prerequisites, but different languages will need
different language servers, which =lsp-mode= will prompt you to auto-install.
=eglot= will not.
** Packages
- [[doom-package:][lsp-mode]]
- [[doom-package:][lsp-ui]]
- [[doom-package:][lsp-ivy]] ([[doom-module:][:completion ivy]])
- [[doom-package:][helm-lsp]] ([[doom-module:][:completion helm]])
- [[doom-package:][consult-lsp]] ([[doom-module:][:completion vertico]])
- [[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.]]
To get LSP working, you'll need to do three things:
1. Enable this module,
2. Install a language server appropriate for your targeted language(s).
3. Enable the [[doom-module:][+lsp]] flag on the [[doom-module:][:lang]] modules you want to enable LSP support for.
Different languages will need different language servers, some of which [[doom-package:][lsp-mode]]
will prompt you to auto-install, but [[doom-package:][eglot]] will not.
A table that lists available language servers and how to install them can be
found [[https://emacs-lsp.github.io/lsp-mode/page/languages/][on the lsp-mode project README]]. The documentation of the module for your
@ -84,15 +80,19 @@ targeted language will contain brief instructions as well.
For eglot users, a list of [[https://github.com/joaotavora/eglot/blob/master/README.md#connecting-to-a-server][default servers supported is on Eglot's README]],
including instructions to register your own.
* TODO Features
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** LSP-powered project search
Without the =+eglot= flag, and when =:completion ivy=, =:completion helm= or
=:completion vertico= is active, LSP is used to search a symbol indexed by the
LSP server :
Without the [[doom-module:][+eglot]] flag, and when [[doom-module:][:completion ivy]], [[doom-module:][:completion helm]] or
[[doom-module:][:completion vertico]] is active, LSP is used to search a symbol indexed by the LSP
server:
| Keybind | Description |
|-----------+-------------------------------------|
| =SPC c j= | Jump to symbol in current workspace |
| =SPC c J= | Jump to symbol in any workspace |
|---------+-------------------------------------|
| [[kbd:][SPC c j]] | Jump to symbol in current workspace |
| [[kbd:][SPC c J]] | Jump to symbol in any workspace |
** Differences between eglot and lsp-mode
Entering the debate about which one to use would be useless. Doom provides an
@ -100,21 +100,39 @@ easy way to switch out lsp client implementations so you can test for yourself
which one you prefer.
Mainly, from a code point of view, lsp-mode has a lot of custom code for UI
(=lsp-ui-peek=, =lsp-ui-sideline=, ...), while eglot is more barebones with a
closer integration with "more basic" emacs packages (=eldoc=, =xref=, ...).
(~lsp-ui-peek~, ~lsp-ui-sideline~, ...), while eglot is more barebones with a
closer integration with "more basic" emacs packages ([[doom-package:][eldoc]], [[doom-package:][xref]], ...).
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Turn off lsp-mode's intrusive features
Many users may not like how many UI elements that lsp-mode adds. They have [[https://emacs-lsp.github.io/lsp-mode/tutorials/how-to-turn-off/][some
excellent documentation]] outlining what these features are called and how to turn
them off.
* Troubleshooting
[[doom-report:][Report an issue?]]
* TODO Troubleshooting
** My language server is not found
Check the entry in the [[../../../docs/faq.org][FAQ]] about "Doom can't find my executables/doesn't inherit
the correct ~PATH~"
** LSP/Eglot is not started automatically in my buffer
Make sure that you added the =+lsp= flag to the language you're using too in
your init.el :
#+BEGIN_SRC diff
Make sure that you have enabled the [[doom-module:][+lsp]] flag on the appropriate module(s) (in
your ~doom!~ block in =$DOOMDIR/init.el=):
#+begin_src diff
:lang
-python
+(python +lsp)
#+END_SRC
#+end_src
* 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

144
modules/tools/magit/README.org
View file

@ -1,78 +1,90 @@
#+TITLE: tools/magit
#+DATE: March 14, 2018
#+SINCE: v2.0.0
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools magit][Issues]] ↖ [[doom-module-source:tools/magit][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools magit
#+SUBTITLE: Wield git like a wizard
#+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]]
- [[#enable-gravatars][Enable Gravatars]]
- [[#enable-granular-diff-highlights-for-all-hunks][Enable granular diff-highlights for all hunks]]
- [[#troubleshooting][Troubleshooting]]
* Description
* Description :unfold:
This module provides Magit, an interface to the Git version control system.
** Maintainers
- [[doom-user:][@hlissner]]
[[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
- +forge ::
Enable Forge; a porcelain for managing Github issues and PRs from within
Emacs. Will take a while on first run to build =emacsql-sqlite=.
** Packages
- [[doom-package:][evil-magit]] if [[doom-module:][:editor evil +everywhere]]
- [[doom-package:][forge]] if [[doom-module:][+forge]]
- [[doom-package:][github-review]]
- [[doom-package:][magit]]
- [[doom-package:][magit-gitflow]]
- [[doom-package:][magit-todos]]
** Hacks
- [[doom-package:][magit]] has been modified to recognize =$XDG_CACHE_HOME/git/credential/socket=.
- [[doom-package:][magit]] has been modified to invalidate the projectile cache when you check out
a new branch or commit.
- [[doom-package:][magit]] has been modified to revert repo buffers (e.g. after changing branches)
when you later switch to them, rather than all at once.
- [[doom-package:][forge]] was modified to defer compilation of emacsql-sqlite until you try to use
forge, rather than when magit first loads (which could be as soon as startup).
** 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://git-scm.com/][Git]]
- [[doom-module:][+forge]] requires [[https://magit.vc/manual/forge/Token-Creation.html#Token-Creation][a Github API token]]
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Start magit with [[kbd:][<leader> g g]] (~M-x magit-status~).
If you are new to Magit, see the [[https://github.com/magit/magit#getting-started][Getting Started]] section of its project readme.
** Maintainers
This module has no dedicated maintainers.
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
** Module Flags
+ =+forge= Enable Forge; a porcelain for managing issues and PRs from within
Emacs. Will take a while on first run to build emacsql-sqlite.
** Plugins
+ [[https://github.com/magit/magit][magit]]
+ [[https://github.com/magit/forge][forge]]* (=+forge=)
+ [[https://github.com/jtatarik/magit-gitflow][magit-gitflow]]
+ [[https://github.com/alphapapa/magit-todos][magit-todos]]
+ [[https://github.com/charignon/github-review][github-review]]
+ [[https://github.com/emacs-evil/evil-magit][evil-magit]]* (=:editor evil +everywhere=)
** Hacks
+ =forge= was modified to defer compilation of emacsql-sqlite until you try to
use forge, rather than when magit first loads (which could be as soon as
startup).
+ =magit= has been modified to recognize
=$XDG_CACHE_HOME/git/credential/socket=.
+ =magit= has been modified to invalidate the projectile cache when you check
out a new branch or commit.
+ =magit= has been modified to revert repo buffers (e.g. after changing
branches) when you later switch to them, rather than all at once.
* Prerequisites
This module requires ~git~.
Forge will require [[https://magit.vc/manual/forge/Token-Creation.html#Token-Creation][a Github API token]] the first time you run =forge-pull=.
* TODO Features
# An in-depth list of features, how to use them, and their dependencies.
* Configuration
Add these to =$DOOMDIR/config.el=.
** Enable Gravatars
This will enable gravatars when viewing commits. The service used by default is [[https://www.libravatar.org/][Libravatar]].
#+BEGIN_SRC emacs-lisp
(setq magit-revision-show-gravatars '("^Author: " . "^Commit: "))
#+END_SRC
To enable gravatars when viewing commits:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! magit
(setq magit-revision-show-gravatars '("^Author: " . "^Commit: ")))
#+end_src
** Enable granular diff-highlights for all hunks
By default, changes are highlighted *linewise* for all but the selected hunk. This
has [[https://magit.vc/manual/magit/Performance.html][performance reasons]]. You can enable character-wise highlights for all
visible hunks with:
#+BEGIN_SRC emacs-lisp
By default, changes are highlighted *linewise* for all but the selected hunk.
This is so for [[https://magit.vc/manual/magit/Performance.html][performance reasons]]. You can enable character-wise highlights for
/all/ visible hunks with:
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(after! magit
(setq magit-diff-refine-hunk 'all))
#+END_SRC
#+end_src
* 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

55
modules/tools/make/README.org Normal file
View file

@ -0,0 +1,55 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools make][Issues]] ↖ [[doom-module-source:tools/make][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools make
#+SUBTITLE: The discount build system
#+CREATED: September 25, 2017
#+SINCE: 2.0.6
* Description :unfold:
This module adds commands for executing Makefile targets.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][makefile-executor]]
** 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 ~make~.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
To invoke a make command: ~M-x +make/run~
To rerun the last make command: ~M-x +make/run-last~
* 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

97
modules/tools/pass/README.org
View file

@ -1,55 +1,66 @@
#+TITLE: tools/pass
#+DATE: May 4, 2020
#+SINCE: V2.0.9
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools pass][Issues]] ↖ [[doom-module-source:tools/pass][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools pass
#+SUBTITLE: A password manager for nerds
#+CREATED: May 04, 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]]
- [[#troubleshooting][Troubleshooting]]
* Description
+ Manage passwords on ~pass~ with power of ~doom~.
+ You can open ~pass~ by =M-x pass=
* Description :unfold:
This module provides an Emacs interface to [[https://www.passwordstore.org/][Pass]].
** Maintainers
This module has no dedicated maintainers.
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module Flags
+ ~+auth~ to enable ~auth-source-pass~
** Module flags
- +auth ::
Allow Emacs to use pass for authentication (via ~auth-source-pass~).
** Plugins
# A list of linked plugins
+ [[https://github.com/NicolasPetton/pass][pass]]
+ [[https://github.com/zx2c4/password-store][password-store]]
+ [[https://github.com/volrath/password-store-otp.el][password-store-otp]]
+ [[https://github.com/DamienCassou/auth-password-store][auth-source-pass (auth-password-store)]]
+ =:completion ivy=
+ [[https://github.com/ecraven/ivy-pass][ivy-pass]]
+ =:completion helm=
+ [[https://github.com/emacs-helm/helm-pass][helm-pass]]
** Packages
- [[doom-package:][helm-pass]] if [[doom-module:][:completion helm]]
- [[doom-package:][ivy-pass]] if [[doom-module:][:completion ivy]]
- [[doom-package:][pass]]
- [[doom-package:][password-store]]
- [[doom-package:][password-store-otp]]
** Hacks
In ~pass-mode~ ~evil~ is put into ~emacs~ state so shown keybindings works correctly, but some keybindings is more ~evil~.
| keybinding | action |
|------------+-------------------------|
| j | pass-next-entry |
| k | pass-previous-entry |
| d | pass-kill |
| C-j | pass-next-directory |
| C-k | pass-previous-directory |
* Prerequisites
+ This module requires that [[https://www.passwordstore.org/][pass]] is installed and setup correctly.
/No hacks documented for this module./
* 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 requires [[https://www.passwordstore.org/][pass]], [[https://gnupg.org/][GnuPG]], and a password library.
* TODO Usage
#+begin_quote
🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Start using this module with ~M-x pass~.
| keybinding | command |
|------------+---------------------------|
| =j= | ~pass-next-entry~ |
| =k= | ~pass-previous-entry~ |
| =d= | ~pass-kill~ |
| =C-j= | ~pass-next-directory~ |
| =C-k= | ~pass-previous-directory~ |
* TODO Configuration
#+begin_quote
🔨 This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]]
#+end_quote
* Troubleshooting
No known 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

105
modules/tools/pdf/README.org
View file

@ -1,55 +1,56 @@
#+TITLE: tools/pdf
#+DATE: February 6, 2018
#+SINCE: v2.0
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools pdf][Issues]] ↖ [[doom-module-source:tools/pdf][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools pdf
#+SUBTITLE: Emacs, your next PDF reader
#+CREATED: February 06, 2018
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#maintainers][Maintainers]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#hacks][Hacks]]
- [[#prerequisites][Prerequisites]]
- [[#building-epdfinfo-on-windows][Building =epdfinfo= on Windows]]
- [[#features][Features]]
- [[#configuration][Configuration]]
- [[#troubleshooting][Troubleshooting]]
* Description :unfold:
This module improves support for reading and interacting with PDF files in
Emacs.
* Description
This module improves support for reading and interacting with PDF files in Emacs.
It uses =pdf-tools=, which is a replacement for the built-in ~doc-view-mode~ for
It uses [[doom-package:][pdf-tools]], which is a replacement for the built-in ~doc-view-mode~ for
PDF files. The key difference being pages are not pre-rendered, but instead
rendered on-demand and stored in memory; a much faster approach, especially for
larger PDFs.
Displaying PDF files is just one function of =pdf-tools=. See [[https://github.com/politza/pdf-tools][its project
website]] for details and videos.
Displaying PDF files is just one function of [[doom-package:][pdf-tools]]. See [[https://github.com/politza/pdf-tools][its project website]]
for details and videos.
** 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/politza/pdf-tools][pdf-tools]]
** Packages
- [[doom-package:][pdf-tools]]
- [[doom-package:][saveplace-pdf-view]]
** Hacks
+ Added out-of-the-box support for HiDPI or Retina displays.
** TODO Hacks
#+begin_quote
🔨 This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]]
#+end_quote
* Prerequisites
This module requires =epdfinfo=, a program the the =pdf-tools= plugin will build
** 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 =epdfinfo=, a program the the [[doom-package:][pdf-tools]] plugin will build
automatically when you open your first pdf file, unless you're on Windows.
Windows users must build it themselves.
You can (re)build =epdfinfo= yourself with ~M-x pdf-tools-install~.
** Building =epdfinfo= on Windows
1. [[https://www.msys2.org/][Install MSYS2]] and update the package database and core packages using the
instructions provided.
2. Update and install dependencies, skipping any you already have
#+BEGIN_SRC sh
2. Update and install dependencies, skipping any you already have:
#+begin_src sh
pacman -Syu
pacman -S base-devel
pacman -S mingw-w64-x86_64-toolchain
@ -57,18 +58,18 @@ Windows users must build it themselves.
pacman -S mingw-w64-x86_64-libpng
pacman -S mingw-w64-x86_64-poppler
pacman -S mingw-w64-x86_64-imagemagick
#+END_SRC
#+end_src
3. Install PDF tools in Emacs, but do not try to compile the server. Instead, get a separate copy of the source somewhere else.
#+BEGIN_SRC sh
3. Install PDF tools in Emacs, but do not try to compile the server. Instead,
get a separate copy of the source somewhere else:
#+begin_src sh
git clone https://github.com/politza/pdf-tools
#+END_SRC
#+end_src
4. Open mingw64 shell (Note: You must use mingw64.exe and not msys2.exe)
5. Compile pdf-tools:
#+BEGIN_SRC sh
#+begin_src sh
# Cask requires python2 (important: not 3!)
pacman -S python2
@ -88,10 +89,10 @@ Windows users must build it themselves.
cd /path/to/pdf-tools
make -s
#+END_SRC
#+end_src
6. This should produce a file =server/epdfinfo.exe=. Copy this file into the
=~/.emacs.d/.local/straight/build/pdf-tools/=.
=$HOME/.emacs.d/.local/straight/build/pdf-tools/=.
7. Start Emacs.
@ -99,11 +100,23 @@ Windows users must build it themselves.
9. Test it out: ~M-x pdf-info-check-epdfinfo~
* 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

52
modules/tools/prodigy/README.org Normal file
View file

@ -0,0 +1,52 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools prodigy][Issues]] ↖ [[doom-module-source:tools/prodigy][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools prodigy
#+SUBTITLE: No sweatshop is complete without child processes
#+CREATED: May 16, 2018
#+SINCE: 21.12.0
* Description :unfold:
This module provides an interface for managing external services from within
Emacs.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
- [[doom-package:][prodigy]]
** 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

70
modules/tools/rgb/README.org
View file

@ -1,35 +1,37 @@
#+TITLE: tools/rgb
#+DATE: May 6, 2020
#+SINCE: 3.0.0
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools rgb][Issues]] ↖ [[doom-module-source:tools/rgb][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools rgb
#+SUBTITLE: Creating color strings
#+CREATED: May 06, 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]]
#+begin_quote
🚧 *This module is deprecated.* The module is too trivial to warrant a module.
#+end_quote
* Description
* Description :unfold:
Highlights color hex values and names with the color itself, and provides tools
to easily modify color values or formats.
** 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://elpa.gnu.org/packages/rainbow-mode.html][rainbow-mode]]
+ [[https://github.com/alphapapa/kurecolor][kurecolor]]
** Packages
- [[doom-package:][kurecolor]]
- [[doom-package:][rainbow-mode]]
* Prerequisites
This module has no prerequisites.
** Hacks
/No hacks documented for this module./
* Features
* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
/This module has no external requirements./
* Usage
=rainbow-mode= provides automatic highlighting to hex color codes, and in
relevant modes, color names (e.g. html color names in =css-mode= or LaTeX color
names in =latex-mode=)
@ -39,13 +41,23 @@ hue of hex colors (and a useful hydra for this, if =:ui hydra= is enabled), as
well as conversion between hex and css colors
* Configuration
=hl-line-mode= overrides the color highlighting of =rainbow-mode=, limiting
the use of that plugin and on-site color changes using =kurecolor=. To
automatically disable it only when =rainbow-mode= is active, you can add the
following hook:
=hl-line-mode= overrides the color highlighting of =rainbow-mode=, limiting the
use of that plugin and on-site color changes using =kurecolor=. To automatically
disable it only when =rainbow-mode= is active, you can add the following hook:
#+BEGIN_SRC elisp
;; ~/.doom.d/config.el
#+begin_src emacs-lisp
;; in $DOOMDIR/config.el
(add-hook! 'rainbow-mode-hook
(hl-line-mode (if rainbow-mode -1 +1)))
#+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

75
modules/tools/taskrunner/README.org
View file

@ -1,38 +1,63 @@
#+TITLE: tools/taskrunner
#+DATE: November 9, 2019
#+SINCE: {replace with next tagged release version}
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools taskrunner][Issues]] ↖ [[doom-module-source:tools/taskrunner][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools taskrunner
#+SUBTITLE: Taskrunner for all your projects
#+CREATED: November 09, 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]]
#+begin_quote
🚧 *This module is deprecated.* The module is too trivial and taskrunner is no
longer maintained.
#+end_quote
* Description
This module integrates [[https://github.com/emacs-taskrunner/emacs-taskrunner][Taskrunner]] into Doom Emacs, which scraps runnable tasks
* Description :unfold:
This module integrates [[doom-package:][taskrunner]] into Doom Emacs, which scraps runnable tasks
from build systems like make, gradle, npm and the like.
** Module Flags
This module provides no flags.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Plugins
+ [[https://github.com/emacs-taskrunner/emacs-taskrunner][emacs-taskrunner]]
+ [[https://github.com/emacs-taskrunner/ivy-taskrunner][ivy-taskrunner]]
+ [[https://github.com/emacs-taskrunner/helm-taskrunner][helm-taskrunner]]
** Module flags
/This module has no flags./
* Prerequisites
This module has no prerequisites.
** Packages
- [[doom-package:][emacs-taskrunner]]
- [[doom-package:][helm-taskrunner]] if [[doom-module:][:completion helm]]
- [[doom-package:][ivy-taskrunner]] if [[doom-module:][:completion ivy]]
* Features
Keybindings
** 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
Keybindings:
| Binding | Description |
| ~p z~ | ~List project tasks~ |
* Configuration
* 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

110
modules/tools/terraform/README.org
View file

@ -1,69 +1,81 @@
#+TITLE: tools/terraform
#+DATE: November 21, 2019
#+SINCE: v2.1.0
#+STARTUP: inlineimages
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools terraform][Issues]] ↖ [[doom-module-source:tools/terraform][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools terraform
#+SUBTITLE: Infrastructure as code
#+CREATED: November 21, 2019
#+SINCE: 21.12.0
* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
- [[#module-flags][Module Flags]]
- [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
- [[#syntax-highlighting][Syntax highlighting]]
- [[#code-formatting][Code formatting]]
- [[#code-navigation][Code navigation]]
- [[#code-completion][Code completion]]
- [[#documentation][Documentation]]
- [[#executing-terraform-commands][Executing Terraform commands]]
- [[#appendix][Appendix]]
- [[#keybindings][Keybindings]]
- [[#localleader][:localleader]]
* Description :unfold:
This module adds support for working with [[https://www.terraform.io][Terraform]] files within Emacs. This
includes syntax highlighting, intelligent code completion, and the ability to
run Terraform commands directly from Emacs.
* Description
This module adds support for working with [[https://www.terraform.io][Terraform]] files in Doom Emacs. This
includes syntax highlighting, intelligent code completion, and the ability to run
Terraform commands directly from Emacs.
** 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/syohex/emacs-terraform-mode][terraform-mode]]
+ [[https://github.com/rafalcieslak/emacs-company-terraform][company-terraform*]]
** Packages
- [[doom-package:][company-terraform]] if [[doom-package:][:completion company]]
- [[doom-package:][terraform-mode]]
* Prerequisites
The =terraform= executable must be installed and accessible from your PATH.
** Hacks
/No hacks documented for this module./
* 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 requires the ~terraform~ executable to be installed and in your
=$PATH=.
* Usage
** Syntax highlighting
Syntax highlighting is provided from =terraform-mode= and =hcl-mode=.
Syntax highlighting is provided from ~terraform-mode~ and ~hcl-mode~.
** Code formatting
=:tools terraform= does not provide code formatting directly, but =:editor
format= works with Terraform files.
[[doom-module:][:tools terraform]] does not provide code formatting directly, but [[doom-module:][:editor format]]
works with Terraform files.
** Code navigation
Code navigation is supported through =imenu= from =terraform-mode=.
Code navigation is supported through [[doom-package:][imenu]] from [[doom-package:][terraform-mode]].
** Code completion
Code completion of Terraform builtins is provided from =company-terraform= and
Code completion of Terraform builtins is provided from [[doom-package:][company-terraform]] and
generally works well despite being generated through a [[https://github.com/rafalcieslak/emacs-company-terraform/blob/master/company-terraform-data.el][static (outdated) file]].
=company-terraform= also provides code completion of resources within your project.
[[doom-package:][company-terraform]] also provides code completion of resources within your
project.
** Documentation
Documentation is accessible through the normal =company-mode= show documentation
functionality, thanks to =company-terraform=.
Documentation is accessible through the normal [[doom-package:][company]] show documentation
functionality, thanks to [[doom-package:][company-terraform]].
** Executing Terraform commands
=:tools terraform= provides commands under the =localleader= to run the most
common Terraform operations (see Keybindings below).
* Appendix
** Keybindings
*** :localleader
[[doom-module:][:tools terraform]] provides commands under [[kbd:][<localleader>]] to run the most common
Terraform operations:
| key | description |
|-----+-----------------------|
| =i= | Run =terraform init= |
| =p= | Run =terraform plan= |
| =a= | Run =terraform apply= |
|-----------------+--------------------------|
| [[kbd:][<localleader> i]] | Runs ~$ terraform init~ |
| [[kbd:][<localleader> p]] | Runs ~$ terraform plan~ |
| [[kbd:][<localleader> a]] | Runs ~$ terraform apply~ |
* 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

51
modules/tools/tmux/README.org Normal file
View file

@ -0,0 +1,51 @@
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools tmux][Issues]] ↖ [[doom-module-source:tools/tmux][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools tmux
#+SUBTITLE: From one multiplexer to another
#+CREATED: October 15, 2021
#+SINCE: 21.12.0
* Description :unfold:
This module provides an API for talking to Tmux sessions.
** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]
** Module flags
/This module has no flags./
** Packages
/This module doesn't install any packages./
** 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

93
modules/tools/upload/README.org
View file

@ -1,64 +1,81 @@
#+TITLE: tools/upload
#+DATE: Feb 19, 2020
#+SINCE: 2.0.9
#+STARTUP: inlineimages nofold
← [[doom-module-index:][Back to module index]] ↙ [[doom-module-issues:::tools upload][Issues]] ↖ [[doom-module-source:tools/upload][Source]] ± [[doom-suggest-edit:][Suggest edits]] ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE: :tools upload
#+SUBTITLE: Map local directories to remotes via ssh/ftp
#+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]]
- [[#root-local-and-root-remote-must-match][~root-local~ and ~root-remote~ must match]]
* Description
* Description :unfold:
Uses ~ssh-deploy~ to map a local folder to a remote one.
From the [[https://github.com/cjohansson/emacs-ssh-deploy/blob/master/README.md][ssh-deploy README]]:
#+BEGIN_QUOTE
#+begin_quote
The ssh-deploy plug-in for Emacs makes it possible to effortlessly deploy local files and directories to remote hosts via Tramp (including but not limited to SSH, SFTP, FTP). It tries to provide functions that can be easily used by custom scripts.
The idea for this plug-in was to mimic the behavior of PhpStorm deployment functionality.
#+END_QUOTE
#+end_quote
** 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/cjohansson/emacs-ssh-deploy][ssh-deploy]]
** Module flags
/This module has no flags./
* Prerequisites
This module has no prerequisites.
** Packages
- [[doom-package:][ssh-deploy]]
** 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
* Features
Uses ~ssh-deploy~ to map a local folder to a remote one. Set
~ssh-deploy-root-remote~ and ~ssh-deploy-root-local~ in a .dir-locals.el file
to establish this mapping.
Example:
#+BEGIN_SRC emacs-lisp
~ssh-deploy-root-remote~ and ~ssh-deploy-root-local~ in a =.dir-locals.el= file
to establish this mapping. E.g.
#+begin_src emacs-lisp
((nil . ((ssh-deploy-root-local . "/local/path/to/project")
(ssh-deploy-root-remote . "/ssh:user@server:/remote/project/")
(ssh-deploy-on-explicit-save . t))))
#+END_SRC
#+end_src
Note: ~ssh-deploy-root-local~ is optional, and will resort to
~doom-project-root~ if unspecified.
#+begin_quote
📌 ~ssh-deploy-root-local~ is optional, and will resort to ~doom-project-root~
if unspecified.
#+end_quote
* TODO Configuration
#+begin_quote
🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote
Check out [[https://github.com/cjohansson/emacs-ssh-deploy#deployment-configuration-examples][Deployment configuration examples]] for some ideas of what's possible.
* Troubleshooting
** ~root-local~ and ~root-remote~ must match
The final directory names much match
#+BEGIN_SRC emacs-lisp
The final directory names much match:
#+begin_src emacs-lisp
((nil . ((ssh-deploy-root-local . "/local/path/to/example-project")
(ssh-deploy-root-remote . "/ssh:user@server:/remote/example-project/")
#+END_SRC
#+end_src
* 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