diff --git a/.dir-locals.el b/.dir-locals.el index f8673c51e..4d02c90b3 100644 --- a/.dir-locals.el +++ b/.dir-locals.el @@ -1,3 +1,2 @@ -((nil (git-commit-major-mode . git-commit-elisp-text-mode) - (fill-column . 80)) - (org-mode (buffer-read-only . t))) +((nil (git-commit-major-mode . git-commit-elisp-text-mode) + (fill-column . 80))) diff --git a/docs/getting_started.org b/docs/getting_started.org deleted file mode 100644 index 13980053f..000000000 --- a/docs/getting_started.org +++ /dev/null @@ -1,1677 +0,0 @@ -#+TITLE: Getting Started Guide -#+STARTUP: nofold - -GNU Emacs is one grand ol' adventure, let alone Doom Emacs. Before you start -you'll need to set up Emacs, Doom, and its packages, then learn how to take care -of your new puppy/operating system. This guide will walk you through installing, -using, configuring and troubleshooting all of these things, to smooth you into -your Emacs journey. - -This guide will gloss over many technicalities so you can get up and running as -soon as possible. A more technical user manual is in the works for aspiring -contributors who want a deeper understanding of how Doom Emacs works. - -#+begin_quote -If you feel like we've missed something, [[https://discord.gg/qvGgnVx][join us on our Discord server]] and let -us know! -#+end_quote - -* Table of Contents :TOC_4: -- [[#install][Install]] - - [[#emacs--dependencies][Emacs & dependencies]] - - [[#on-linux][On Linux]] - - [[#ubuntu][Ubuntu]] - - [[#fedora][Fedora]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] - - [[#opensuse][openSUSE]] - - [[#gentoo-linux][Gentoo Linux]] - - [[#on-macos][On macOS]] - - [[#with-homebrew][With Homebrew]] - - [[#with-macports][With MacPorts]] - - [[#on-windows][On Windows]] - - [[#with-chocolatey--scoop][With chocolatey / scoop]] - - [[#with-a-precompiled-binary--git-bash][With a precompiled binary + Git Bash]] - - [[#with-wsl--ubuntu-1804-lts][With WSL + Ubuntu 18.04 LTS]] - - [[#doom-emacs][Doom Emacs]] - - [[#the-bindoom-utility][The ~bin/doom~ utility]] - - [[#install-doom-manually][Install Doom Manually]] - - [[#install-doom-alongside-other-configs-with-chemacs2][Install Doom alongside other configs (with Chemacs2)]] - - [[#externalsystem-dependencies][External/system dependencies]] -- [[#update--rollback][Update & Rollback]] - - [[#rollback][Rollback]] - - [[#updowngrading-emacs][Up/Downgrading Emacs]] -- [[#migrate][Migrate]] - - [[#from-vanilla-emacs][From vanilla Emacs]] - - [[#from-spacemacs][From Spacemacs]] -- [[#configure][Configure]] - - [[#modules][Modules]] - - [[#package-management][Package management]] - - [[#installing-packages][Installing packages]] - - [[#installing-packages-from-external-sources][Installing packages from external sources]] - - [[#pinning-packages-to-specific-commits][Pinning packages to specific commits]] - - [[#disabling-packages][Disabling packages]] - - [[#changing-a-recipe-for-an-included-package][Changing a recipe for an included package]] - - [[#usingloading-local-packages][Using/loading local packages]] - - [[#configuring-doom][Configuring Doom]] - - [[#configuring-packages][Configuring packages]] - - [[#reloading-your-config][Reloading your config]] - - [[#binding-keys][Binding keys]] - - [[#writing-your-own-modules][Writing your own modules]] - - [[#file-structure][File structure]] - - [[#initel][=init.el=]] - - [[#configel][=config.el=]] - - [[#packagesel][=packages.el=]] - - [[#autoloadel-or-autoloadel][=autoload/*.el= OR =autoload.el=]] - - [[#doctorel][=doctor.el=]] - - [[#cliel][=cli.el=]] - - [[#testtest-el][=test/**/test-*.el=]] - - [[#additional-files][Additional files]] - - [[#load-order][Load order]] - - [[#flags][Flags]] - - [[#doom-cookies][Doom cookies]] - - [[#if][~;;;###if~]] - - [[#package][~;;;###package~]] - - [[#autodef][~;;;###autodef~]] - - [[#common-mistakes-when-configuring-doom-emacs][Common mistakes when configuring Doom Emacs]] - - [[#packages-are-eagerly-loaded][Packages are eagerly loaded]] - - [[#manual-package-management][Manual package management]] - - [[#using-org-babel-do-load-languages-to-load-your-babel-packages][Using ~org-babel-do-load-languages~ to load your babel packages]] - - [[#using-delete-trailing-whitespaces-or-whitespace-cleanup-to-manage-leftover-whitespace][Using ~delete-trailing-whitespaces~ or ~whitespace-cleanup~ to manage leftover whitespace]] -- [[#troubleshoot][Troubleshoot]] - - [[#looking-up-documentation-and-state-from-within-emacs][Looking up documentation and state from within Emacs]] - - [[#variables-functions-faces-etc][Variables, functions, faces, etc.]] - - [[#for-doom-modules-packages-autodefs-etc][For Doom Modules, packages, autodefs, etc.]] - - [[#how-to-extract-a-backtrace-from-an-error][How to extract a backtrace from an error]] - - [[#enabling-debug-on-error][Enabling ~debug-on-error~]] - - [[#a-backtrace-from-bindoom][A backtrace from ~bin/doom~]] - - [[#evaluating-elisp-on-the-fly][Evaluating Elisp on-the-fly]] - - [[#how-to-determine-the-origin-of-a-bug][How to determine the origin of a bug]] - - [[#testing-in-dooms-sandbox][Testing in Doom's sandbox]] - - [[#opening-the-sandbox][Opening the sandbox]] - - [[#launching-the-sandbox][Launching the sandbox]] - - [[#testing-packages-in-the-sandbox][Testing packages in the sandbox]] - - [[#bisecting-your-private-config][Bisecting your private config]] - - [[#bisecting-doom-emacs][Bisecting Doom Emacs]] - -* Install -This is what you'll have installed by the end of this section: - -- Git 2.23+ -- Emacs 27.1+ *(27.2 is recommended, or [[https://www.emacswiki.org/emacs/GccEmacs][native-comp]])* -- [[https://github.com/BurntSushi/ripgrep][ripgrep]] 11.0+ -- GNU Find -- (Optional) [[https://github.com/sharkdp/fd][fd]] 7.3.0+ (known as ~fd-find~ on Debian, Ubuntu & derivatives) -- - improves performance for many file indexing commands - -These packages ought to be available through the package managers of your -operating system; i.e. homebrew & macports on macOS, scoop/chocolatey on -Windows, or pacman/aptitude/etc on the various Linux distributions. - -** Emacs & dependencies -*** On Linux -Installation instructions for Emacs 27.1+ are listed below for many popular -Linux distributions. In the unusual case that 27.1 or newer is unavailable on -your system, you'll have to [[https://www.gnu.org/software/emacs/manual/html_node/efaq/Installing-Emacs.html][build it from source]] instead. - -**** Ubuntu -Emacs 27.x is not available through Ubuntu's package manager out-of-the-box, but -is available through a PPA: - -#+BEGIN_SRC bash -add-apt-repository ppa:kelleyk/emacs -apt-get update -apt-get install emacs27 -#+END_SRC - -Or through snap: - -#+BEGIN_SRC bash -snap install emacs --classic -#+END_SRC - -In some cases, you may need to delete old version of emacs and it's dependencies first, before installing emacs27: -#+BEGIN_SRC bash -sudo apt remove emacs -sudo apt autoremove -#+END_SRC - -***** Other dependencies -Then install Doom's other dependencies: -#+BEGIN_SRC bash -apt-get install ripgrep fd-find - -# On 18.04 or older, ripgrep and fd-find won't be available in -# official repos. You'll need to install them another way, e.g. -sudo dpkg -i fd_8.2.1_amd64.deb # adapt version number and architecture -sudo dpkg -i fd_8.2.1_amd64.deb # adapt version number and architecture -#+END_SRC - -**** Fedora -#+BEGIN_SRC bash -# required dependencies -dnf install emacs git ripgrep -# optional dependencies -dnf install fd-find # is 'fd' in Fedora <28 -#+END_SRC - -**** Arch Linux -#+BEGIN_SRC bash -# required dependencies -pacman -S git emacs ripgrep -# optional dependencies -pacman -S fd -#+END_SRC - -The above installs Emacs 27 (at the time of writing). - -**** NixOS -On NixOS Emacs 27.2 can be installed via ~nix-env -Ai nixos.emacs~, or -permanently with the following added to ~etc/nixos/configuration.nix~: - -#+BEGIN_SRC nix -environment.systemPackages = with pkgs; [ - # required dependencies - git - emacs # Emacs 27.2 - ripgrep - # optional dependencies - coreutils # basic GNU utilities - fd - clang -]; -#+END_SRC - -Installing Emacs 28+ will require [[https://github.com/nix-community/emacs-overlay/issues][nix-community/emacs-overlay]]: -#+BEGIN_SRC nix -nixpkgs.overlays = [ - (import (builtins.fetchTarball https://github.com/nix-community/emacs-overlay/archive/master.tar.gz)) -]; - -environment.systemPackages = [ - pkgs.emacsGcc # Installs Emacs 28 + native-comp -]; -#+END_SRC - -**** openSUSE -***** Emacs 27.1 -Emacs can be installed from the [[https://software.opensuse.org/download.html?project=editors&package=emacs][package list]], or manually via zypper. - -For example, to install on openSUSE Leap 15.1 (requires root): -#+BEGIN_SRC bash -zypper addrepo https://download.opensuse.org/repositories/editors/openSUSE_Leap_15.1/editors.repo -zypper refresh -zypper install emacs -#+END_SRC - -If you already have an older version of Emacs installed, you will be prompted to -install the update candidate (Emacs 27.1). - -***** ripgrep -Download ripgrep 11.0.2 from [[https://software.opensuse.org/download/package?package=ripgrep&project=openSUSE%3AFactory][the package list]] or installed manually (requires -root). -#+BEGIN_SRC bash -zypper addrepo https://download.opensuse.org/repositories/openSUSE:Factory/standard/openSUSE:Factory.repo -zypper refresh -zypper install ripgrep -#+END_SRC - -Only ripgrep 0.8.1 is officially available on Leap 15.1 and 15.2, so you will -need to install Rust to build ripgrep from source. Rust can be downloaded [[https://software.opensuse.org/package/rust][from -the package list]] or installed manually via zypper (requires root), e.g. -#+BEGIN_SRC bash -zypper addrepo https://download.opensuse.org/repositories/openSUSE:Leap:15.1:Update/standard/openSUSE:Leap:15.1:Update.repo -zypper refresh -zypper install rust -#+END_SRC - -See the [[https://github.com/BurntSushi/ripgrep#building][ripgrep documentation]] for instructions on building from source. - -**** Gentoo Linux -Everything you need is in Gentoo's official =::gentoo= repository. - -***** Emacs -To use Emacs graphically, enable the =gui= USE flag. And enable the =xft= USE flag to render fonts correctly (see -[[https://github.com/hlissner/doom-emacs/issues/4876][issue #4876]]) -#+begin_src sh -echo "app-editors/emacs gui xft" >> /etc/portage/package.use/emacs -#+end_src - -To install the latest unmasked version compatible with Doom: -#+begin_src sh -emerge '>=app-editors/emacs-27.0' -#+end_src - -Or, for GCCEmacs/Native Compilation, use the live ebuild for version 28.0 with the =jit= USE flag: - -Unmask the desired ebuild by adding the following to =package.accept_keywords=: -#+begin_src -=app-editors/emacs-28.0.9999 ** -#+end_src - -Add the =jit= USE flag to =package.use=: -#+begin_src -=app-editors/emacs-28.0.9999 jit -#+end_src - -And emerge: -#+begin_src sh -emerge =app-editors/emacs-28.0.9999 -#+end_src - -***** Other Dependencies -#+begin_src sh -# required -emerge '>=dev-vcs/git-2.23' '>=sys-apps/ripgrep-11.0' sys-apps/findutils -# optional -emerge '>=sys-apps/fd-7.3.0' -#+end_src - -*** On macOS -MacOS users have many options for installing Emacs, but not all of them are well -suited to Doom. Before we get to that you'll need either the Homebrew or -MacPorts package manager installed (you only need one): - -+ [[http://brew.sh/][How to install Homebrew]] -+ [[https://www.macports.org/install.php][How to install MacPorts]] - -**** With Homebrew -First, Doom's dependencies: -#+BEGIN_SRC bash -# required dependencies -brew install git ripgrep -# optional dependencies -brew install coreutils fd -# Installs clang -xcode-select --install -#+END_SRC - -For Emacs itself, these three formulas are the best options, ordered from most -to least recommended for Doom (based on compatibility). - -- [[https://bitbucket.org/mituharu/emacs-mac/overview][emacs-mac]]. It offers good integration - with macOS, native emojis and better childframe support. - #+BEGIN_SRC bash - brew tap railwaycat/emacsmacport - brew install emacs-mac --with-modules - ln -s /usr/local/opt/emacs-mac/Emacs.app /Applications/Emacs.app - #+END_SRC - -- [[https://github.com/d12frosted/homebrew-emacs-plus][emacs-plus]]. Some users have - experienced [flashing artifacts when scrolling](https://github.com/d12frosted/homebrew-emacs-plus/issues/314): - #+BEGIN_SRC bash - brew tap d12frosted/emacs-plus - brew install emacs-plus - ln -s /usr/local/opt/emacs-plus/Emacs.app /Applications/Emacs.app - #+END_SRC - -- [[https://formulae.brew.sh/formula/emacs][emacs]] is another acceptable option, **but does not provide a Emacs.app**: - #+BEGIN_SRC bash - brew install emacs - #+END_SRC - -***** Where *not* to install Emacs from -These builds/forks have known compatibility issues with Doom and are *very -likely* to cause issues later on. They are not recommended: - -+ emacsformacosx.com -+ ~brew cask install emacs~ (installs from emacsformacosx.com) -+ AquaMacs -+ XEmacs - -**** With MacPorts -There are four ports (at time of writing) available through MacPorts, and they -are all acceptable options: - -+ [[https://ports.macports.org/port/emacs/summary][emacs]] (27.2) and [[https://ports.macports.org/port/emacs-devel/summary][emacs-devel]] (28) -- Installs terminal-only Emacs -+ [[https://ports.macports.org/port/emacs-app/summary][emacs-app]] (27.2), [[https://ports.macports.org/port/emacs-app-devel/summary][emacs-app-devel]] (28) -- Installs GUI Emacs -+ [[https://ports.macports.org/port/emacs-mac-app/summary][emacs-mac-app]] (27.2) -- the [[https://bitbucket.org/mituharu/emacs-mac][Mitsuharu Yamamoto mac port]] - -Some of these ports do not add an =emacs= binary to your ~PATH~, which is -necessary for Doom's installation process. You'll have to do so yourself by -adding this to your shell config: - -#+BEGIN_SRC sh -# Add this to ~/.zshrc or ~/.bash_profile -export PATH="/Applications/MacPorts/Emacs.app/Contents/MacOS:$PATH" -#+END_SRC - -Or by replacing ~/usr/local/bin/emacs~ with a shim script containing: -#+BEGIN_SRC -#!/bin/sh -/Applications/MacPorts/Emacs.app/Contents/MacOS/Emacs "$@" -#+END_SRC - -*** On Windows -#+begin_quote -*WARNING:* Emacs on Windows is much slower than its Linux or macOS counterparts. -There are some suggestions on how to speed it up later in this section. -#+end_quote - -There are three methods for installing Emacs 27.x on Windows, each with their -pros and cons: - -+ With chocolatey/scoop -+ With a precompiled binary + Git Bash -+ With WSL2 + Ubuntu - -If you don't know which to choose, I highly recommend WSL; it produces the -fastest and most stable environment of the three, but has the most complex -installation process. - -Before moving on to installing Emacs et co, a few steps to prepare Windows for -Emacs are necessary: - -1. Create a ~HOME~ [[https://mywindowshub.com/how-to-edit-system-environment-variables-for-a-user-in-windows-10/][system environment variable]]. - - Set it to =C:\Users\USERNAME\=, otherwise Emacs will treat - =C:\Users\USERNAME\AppData\Roaming= as your ~HOME~, which will cause issues - later. - -2. Add =C:\Users\USERNAME\.emacs.d\bin= to your ~PATH~. - - This way, you don't have to type all of =C:\Users\USERNAME\.emacs.d\bin\doom= - every time you need to run this script (and you'll need to, often). - - #+begin_quote - A pre-existing PATH variable should already exist among your system - variables. It contains a string of file paths separated by colons; - ~pathA:pathB:pathC~. Prepend the path to bin/doom to that string, like so: - ~C:\Users\username\.emacs.d\bin:pathA:pathB:pathC~ - #+end_quote - -3. Restart your system so your new values for ~HOME~ and ~PATH~ take effect. - -Now we're ready to move on! - -**** With [[https://chocolatey.org/][chocolatey]] / scoop -[[https://chocolatey.org/][Chocolatey]] is a package manager for Windows, and is the simplest way to install -Emacs and Doom's dependencies: -#+BEGIN_SRC sh -choco install git emacs ripgrep -# Optional dependencies -choco install fd llvm -#+END_SRC - -Scoop will work too, but because Emacs is a GUI application you'll need to -enable the 'extras' Scoop bucket: -#+BEGIN_SRC sh -scoop bucket add extras -scoop install git emacs ripgrep -# Optional dependencies -scoop install fd llvm -#+END_SRC - -**** With a precompiled binary + Git Bash -(Credit goes to @earvingad and [[https://earvingad.github.io/posts/doom_emacs_windows/][his fantastic tutorial]] for informing this guide) - -1. Download and install Git from https://git-scm.com/download/win -2. Download and extract Emacs, ripgrep and fd where you want them, but in - different folders: - - Emacs 27.2 from http://ftp.wayne.edu/gnu/emacs/windows/emacs-27/ - - Ripgrep from https://github.com/BurntSushi/ripgrep/releases - - (optional) fd from https://github.com/sharkdp/fd/releases -3. Add the three folders from step 2 to your ~PATH~ - - Go to Control panel -> User Accounts -> Change my environment variables. - - Click "New", type HOME and set your C:\Users\USERNAME and OK. - - Select "Path", click "edit", prepend =C:\path\to\the\emacs\bin:= to it and - click OK. - - Select "Path", click "edit", prepend =C:\path\to\the\ripgrep:= to it and - click OK. - - Select "Path", click "edit", prepend =C:\path\to\the\fd:= to it and click - OK. - - Click Ok. - -And done! Keep git-bash.exe open, you'll need it for the rest of this guide. - -#+begin_quote -*IMPORTANT:* you'll need to open git-bash.exe whenever you want to run a -bin/doom command. -#+end_quote - -**** With WSL + Ubuntu 18.04 LTS -(Credit goes to @lunias and [[https://ethanaa.com/blog/switching-to-doom-emacs/#installing-on-windows-10 -][his fantastic tutorial]] for informing this guide) - -1. Install Powershell as admin (Windows key + x) with: - #+BEGIN_SRC - Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux - #+END_SRC -2. Restart your Computer -3. Download and install Ubuntu 18.04 L>TS from the Microsoft Store -4. Launch Ubuntu 18.04 LTS -5. Update and upgrade Ubuntu - #+BEGIN_SRC - sudo apt update && sudo apt upgrade - #+END_SRC -6. Then install Emacs: - #+BEGIN_SRC sh - sudo add-apt-repository ppa:kelleyk/emacs - sudo apt update - sudo apt install emacs27 - #+END_SRC -7. Then Doom's dependencies: - #+BEGIN_SRC sh - # required dependencies - sudo apt-get install git ripgrep - # optional dependencies - sudo apt-get install fd-find - #+END_SRC - -And done! Keep Ubuntu open, you'll need it for the rest of this guide. - -** Doom Emacs -With Emacs and Doom's dependencies installed, next is to install Doom Emacs -itself: - -#+BEGIN_SRC bash -git clone https://github.com/hlissner/doom-emacs ~/.emacs.d -~/.emacs.d/bin/doom install -#+END_SRC - -=doom install= will set up your =DOOMDIR= at =~/.doom.d= (if it doesn't already -exist) and will work you through the first-time setup of Doom Emacs. Carefully -follow any instructions it puts out. - -If this is your first time, you should run ~doom doctor~. This will diagnose -common issues with your system or config. - -#+BEGIN_QUOTE -If you'd like a more technical break down of ~doom install~, it's been -translated into shell commands below, in the "Install Doom Manually" section. -#+END_QUOTE - -*** The ~bin/doom~ utility -This utility is your new best friend. It won't spot you a beer, but it'll -shoulder much of the work associated with managing and maintaining your Doom -Emacs configuration, and then some. Not least of which is installation of and -updating Doom and your installed packages. - -It exposes a variety of commands. ~bin/doom help~ will list them all, but here -is a summary of the most important ones: - -+ ~doom sync~: This synchronizes your config with Doom Emacs. It ensures that - needed packages are installed, orphaned packages are removed and necessary - metadata correctly generated. Run this whenever you modify your ~doom!~ block - or =packages.el= file. You'll need ~doom sync -u~ if you override the recipe - of package installed by another module. -+ ~doom upgrade~: Updates Doom Emacs (if available) and all its packages. -+ ~doom env~: (Re)generates an "envvar file", which is a snapshot of your - shell environment that Doom loads at startup. If your app launcher or OS - launches Emacs in the wrong environment you will need this. **This is required - for GUI Emacs users on MacOS.** -+ ~doom doctor~: If Doom misbehaves, the doc will diagnose common issues with - your installation, system and environment. -+ ~doom purge~: Over time, the repositories for Doom's plugins will accumulate. - Run this command from time to time to delete old, orphaned packages, and with - the ~-g~ switch to compact existing package repos. - -Use ~doom help~ to see an overview of the available commands that =doom= -provides, and ~doom help COMMAND~ to display documentation for a particular -~COMMAND~. - -#+begin_quote -I recommend you add =~/.emacs.d/bin= to your ~PATH~ so you can call =doom= -directly and from anywhere. Accomplish this by adding this to your .bashrc or -.zshrc file: ~export PATH="$HOME/.emacs.d/bin:$PATH"~ -#+end_quote - -*** Install Doom Manually -If you'd rather install Doom yourself, instead of rely on the magic of =doom -install=, here is its equivalent in bash shell commands (assuming -=hlissner/doom-emacs= has been cloned to =~/.emacs.d=): - -#+BEGIN_SRC bash -# So we don't have to write ~/.emacs.d/bin/doom every time -PATH="$HOME/.emacs.d/bin:$PATH" - -# Create a directory for our private config -mkdir ~/.doom.d # or ~/.config/doom - -# The init.example.el file contains an example doom! call, which tells Doom what -# modules to load and in what order. -cp ~/.emacs.d/init.example.el ~/.doom.d/init.el -cp ~/.emacs.d/core/templates/config.example.el ~/.doom.d/config.el -cp ~/.emacs.d/core/templates/packages.example.el ~/.doom.d/packages.el - -# You might want to edit ~/.doom.d/init.el here and make sure you only have the -# modules you want enabled. - -# Then synchronize Doom with your config: -doom sync - -# If you know Emacs won't be launched from your shell environment (e.g. you're -# on macOS or use an app launcher that doesn't launch programs with the correct -# shell) then create an envvar file to ensure Doom correctly inherits your shell -# environment. -# -# If you don't know whether you need this or not, there's no harm in doing it -# anyway. `doom install` will have prompted you to generate one. If you -# responded no, you can generate it later with the following command: -doom env - -# Lastly, install the icon fonts Doom uses: -emacs --batch -f all-the-icons-install-fonts -# On Windows, `all-the-icons-install-fonts` will only download the fonts, you'll -# have to install them by hand afterwards! -#+END_SRC - -To understand the purpose of the =~/.doom.d= directory and =~/.doom.d/init.el= -file, see the [[#configure][Configure]] section further below. - -*** Install Doom alongside other configs (with Chemacs2) -[[https://github.com/plexus/chemacs2][Chemacs2]] is a bootloader for Emacs. It allows you to switch between multiple -Emacs configurations. Here is a quick guide for setting it up with Doom Emacs as -the default config: - -1. First, install Doom somewhere: - #+BEGIN_SRC sh :eval no - git clone https://github.com/hlissner/doom-emacs ~/doom-emacs - ~/doom-emacs/bin/doom install - #+END_SRC - -2. Move aside any existing config and install Chemacs2 as your new =~/.emacs.d=: - #+BEGIN_SRC bash :eval no - [ -f ~/.emacs ] && mv ~/.emacs ~/.emacs.bak - [ -d ~/.emacs.d ] && mv ~/.emacs.d ~/.emacs.legacy - git clone https://github.com/plexus/chemacs2.git ~/.emacs.d - #+END_SRC - -3. Create =~/.emacs-profiles.el= with a list of your Emacs profiles. This file - is structured like a =.dir-locals.el= file. Here is an example with Doom (as - the default), Spacemacs, and Prelude: - #+BEGIN_SRC emacs-lisp :eval no - (("default" . ((user-emacs-directory . "~/doom-emacs"))) - ("legacy" . ((user-emacs-directory . "~/.emacs.legacy"))) - ("spacemacs" . ((user-emacs-directory . "~/spacemacs")))) - #+END_SRC - -To start Emacs with a specific config, use the =--with-profile= option: - -#+BEGIN_SRC bash -emacs --with-profile spacemacs -#+END_SRC - -If no profile is specified, the =default= profile is used. - -** External/system dependencies -Doom is comprised of approximately 160 modules which provide its features, -language support and integration with external tools. Many of these have -external dependencies that you must install yourself. You'll find what a module -needs and how to install them in that module's README.org file or by running -~bin/doom doctor~. - -The [[file:modules.org][Module Index]] lists all Doom's available modules, with links to their -documentation. Documentation is a work-in-progrees; some modules may not have -README.org files yet! - -#+begin_quote -Use ~M-x doom/help-modules~ (bound to =SPC h d m= or =C-h d m=) to jump to a -module's documentation from within Doom, otherwise, place your cursor on a -module in your ~doom!~ block (in =~/.doom.d/init.el=) and press =K= to jump to -its documentation (or =gd= to jump to its source code). =C-c g k= and =C-c g d= -for non-evil users, respectively. -#+end_quote - -* Update & Rollback -Doom is an active project and many of its 300+ packages are in active -development as well. It is wise to occasionally update: -#+BEGIN_SRC bash -doom upgrade # or 'doom up' -#+END_SRC - -If you want to update Doom manually, ~doom upgrade~ is equivalent to: -#+BEGIN_SRC bash -cd ~/.emacs.d -git pull # updates Doom -doom clean # Ensure your config isn't byte-compiled -doom sync # synchronizes your config with Doom Emacs -doom update # updates installed packages -#+END_SRC - -To upgrade only your packages (and not Doom itself): - -#+BEGIN_SRC bash -doom upgrade --packages -#+END_SRC - -#+begin_quote -To minimize issues while upgrading, avoid modifying Doom's source files in -=~/.emacs.d=. All your customization should be kept in your =DOOMDIR= (e.g. -=~/.doom.d=). Read the [[#Configure][Configure]] section for more on configuring Doom. -#+end_quote - -** TODO Rollback -The =bin/doom= script doesn't currently offer rollback support for Doom or its -packages (yet). - -** Up/Downgrading Emacs -*You may encounter errors after up/downgrading Emacs.* Run ~doom sync~ on the -command line after changing the installed version of Emacs. If you've changed -the major version (e.g. 27 -> 28 or vice versa) run ~doom build~ too. - -+ ~doom sync~ will re-index any built-in/site loaddef files. This is especially - necessary if paths to built-in libraries have changed. -+ ~doom build~ will recompile all your installed packages, which is necessary - because Emacs bytecode not generally forward compatible across major releases - (e.g. 27 -> 28). Alternatively, reinstall all your packages by deleting - =~/.emacs.d/.local=, then run ~doom sync~. - -* TODO Migrate -If you're here from another Emacs distribution (or your own), here are a few -things to be aware of while you convert your old config to Doom: - -+ Doom does not use =package.el= to manage its packages, but ~use-package~ does! - You will see errors if you have ~:ensure ...~ properties in your ~use-package~ - blocks. Remove these and, instead, add ~package!~ declarations to - =~/.doom.d/packages.el= to install your packages. - - See [[#package-management]["Package Management"]], further in this guide. - -(This section is incomplete) - -** TODO From vanilla Emacs -#+begin_quote -Have you migrated from your own config? Help me flesh out this section by -letting me know what kind of hurdles you faced in doing so. You'll find me [[https://discord.gg/qvGgnVx][on -our Discord server]]. -#+end_quote - -** TODO From Spacemacs -#+begin_quote -Have you migrated from Spacemacs? Help me flesh out this section by letting me -know what kind of hurdles you faced in doing so. You'll find me [[https://discord.gg/qvGgnVx][on our Discord -server]]. -#+end_quote - -* Configure -You can configure Doom by tweaking the files found in your =DOOMDIR=. Doom -expects this directory to be found in one of: - -1. =~/.config/doom= (respects ~$XDG_CONFIG_HOME~) -2. or =~/.doom.d= - -This directory is referred to as your =DOOMDIR=. Only one of these directories -should exist (Doom will only recognize one). - -#+begin_quote -Change the =DOOMDIR= environment variable to change where Doom looks for this -directory. Symlinks will work as well. -#+end_quote - -When you ran ~doom install~, it deployed a simple Doom configuration to your -=DOOMDIR=, comprised of these three files: - -+ init.el :: Where you'll find your ~doom!~ block, which controls what Doom - modules are enabled and in what order they will be loaded. - - This file is evaluated early when Emacs is starting up; before any other - module has loaded. You generally shouldn't add code to this file unless you're - targeting Doom's CLI or something that needs to be configured very early in - the startup process. -+ config.el :: Here is where 99.99% of your private configuration should go. - Anything in here is evaluated /after/ all other modules have loaded, when - starting up Emacs. -+ packages.el :: Package management is done from this file; where you'll declare - what packages to install and where from. - -#+begin_quote -Note: do not use ~M-x customize~ or the customize API in general. Doom is -designed to be configured programmatically from your config.el, which can -conflict with Customize's way of modifying variables. - -If you're concerned about ~defcustom~ setters, Doom has a ~setq!~ macro that -will trigger them. -#+end_quote - -** Modules -Doom consists of around 160 modules and growing. A Doom module is a bundle of -packages, configuration and commands, organized into a unit that can be toggled -easily by tweaking your ~doom!~ block (found in =$DOOMDIR/init.el=). - -#+begin_quote -If =$DOOMDIR/init.el= doesn't exist, you haven't run ~doom install~ yet. See [[#install][the -"Install" section]] above. -#+end_quote - -Your ~doom!~ block should look something like this: - -#+BEGIN_SRC emacs-lisp -;; To comment something out, you insert at least one semicolon before it and the -;; Emacs Lisp interpreter will ignore everything until the end of the line. -(doom! :lang - python ; this module is not commented, therefore enabled - ;;javascript ; this module is commented out, therefore disabled - ;;lua ; this module is disabled - ruby ; this module is enabled - php) ; this module is enabled -#+END_SRC - -It controls what modules are enabled and in what order they are loaded. Some -modules have *optional features* that can be enabled by passing them flags, -denoted by a plus prefix: - -#+BEGIN_SRC emacs-lisp -(doom! :completion - (company +childframe) - :lang - (csharp +unity) - (org +brain +dragndrop +gnuplot +hugo +jupyter) - (sh +fish)) -#+END_SRC - -Different modules support different flags. You'll find a comprehensive list of -available modules and their supported flags in [[file:modules.org][Module Index]]. Flags that a -module does not recognize will be silently ignored. - -#+begin_quote -*IMPORTANT:* any changes to your ~doom!~ block won't take effect until you run - ~doom sync~ on the command line. -#+end_quote - -#+begin_quote -~doom doctor~ will detect issues with your ~doom!~ block, such as duplicate or -misspelled modules and flags. -#+end_quote - -** Package management -**Doom Emacs does not use package.el** (the package manager built into Emacs). -Instead, it uses its own declarative package manager built on top of -[[https://github.com/raxod502/straight.el][straight.el]]. - -Packages are declared in ~packages.el~ files. You'll find one in your =DOOMDIR= -and in many of Doom's modules. Read on to learn how to use this system to -install your own packages. - -#+begin_quote -*WARNING:* Do not install packages directly (with ~M-x package-install~ or ~M-x -straight-use-package~). Without an accompanying ~package!~ declaration somewhere -these packages will be forgotten when you restart Emacs and uninstalled the next -time you run ~doom sync~ or ~doom purge~. -#+end_quote - -#+begin_quote -*WARNING:* If you're here from another Emacs distro (or vanilla Emacs), be wary -of the ~:ensure~ property in ~use-package~ blocks, because it will attempt (and -fail) to install packages through package.el. Tutorials will recommend you -install packages this way too! -#+end_quote - -*** Installing packages -To install a package, add a ~package!~ declaration for it to -=DOOMDIR/packages.el=: -#+BEGIN_SRC emacs-lisp -;; Install a package named "example" from ELPA, MELPA, or Emacsmirror -(package! example) -#+END_SRC - -If a package could not be found in any known repo you will get an error like: - -#+begin_quote -Could not find package X in recipe repositories: (org-elpa melpa gnu-elpa-mirror -emacsmirror-mirror) -#+end_quote - -The most likely cause for this is either: - -- You've misspelled the package's name. -- Or the package really doesn't exist on ELPA, MELPA, or EmacsMirror and you'll - need to [[*Installing packages from external sources][specify a recipe for it]]. - -~package!~ will return non-nil if the package is cleared for install and hasn't -been disabled elsewhere. Use this fact to chain package dependencies together. -e.g. -#+BEGIN_SRC elisp -(when (package! example) - (package! plugin-that-example-depends-on)) -#+END_SRC - -#+begin_quote -*IMPORTANT:* New packages won't be installed until you run ~doom sync~. -#+end_quote - -*** Installing packages from external sources -To install a package straight from an external source (like github, gitlab, -etc), you'll need to specify a [[https://github.com/raxod502/straight.el#the-recipe-format][MELPA-style straight recipe]]: - -Here are a few examples: -#+BEGIN_SRC elisp -;; Install it directly from a github repository. For this to work, the package -;; must have an appropriate PACKAGENAME.el file which must contain at least a -;; Package-Version or Version line in its header. -(package! example - :recipe (:host github :repo "username/my-example-fork")) - -;; If the source files for a package are in a subdirectory in said repo, use -;; `:files' to target them. -(package! example :recipe - (:host github - :repo "username/my-example-fork" - :files ("*.el" "src/lisp/*.el"))) - -;; To grab a particular branch or tag: -(package! example :recipe - (:host gitlab - :repo "username/my-example-fork" - :branch "develop")) - -;; If a package has a default recipe on MELPA or emacsmirror, you may omit -;; keywords and the recipe will inherit the rest of the recipe from their -;; original. -(package! example :recipe (:branch "develop")) - -;; If the repo pulls in many unneeded submodules, you can disable recursive cloning -(package! example :recipe (:nonrecursive t)) - -;; A package can be installed straight from a git repo by setting :host to nil: -(package! example - :recipe (:host nil :repo "https://some/git/repo")) -#+END_SRC - -The specification for the ~package!~ macro's ~:recipe~ is laid out [[https://github.com/raxod502/straight.el#the-recipe-format][in -Straight.el's README]]. - -#+begin_quote -*IMPORTANT:* Run ~bin/doom sync~ whenever you modify packages.el files to -ensure your changes take effect. -#+end_quote - -*** Pinning packages to specific commits -All of Doom's packages are pinned by default. A pinned package is a package -locked to a specific commit, like so: -#+BEGIN_SRC elisp -(package! evil :pin "e00626d9fd") -#+END_SRC - -To unpin a package, use the ~unpin!~ macro: -#+BEGIN_SRC elisp -(unpin! evil) - -;; It can be used to unpin multiple packages at once -(unpin! evil helm org-mode) - -;; Or to unpin all packages in modules -(unpin! (:lang python ruby rust) (:tools docker)) - -;; Or to unpin an entire category of modules -(unpin! :completion :lang :tools) - -;; This will work too, if you prefer the syntax, but it provides no concise -;; syntax for unpinning multiple packages: -(package! helm :pin nil) -#+END_SRC - -Though it is *highly* discouraged, you may unpin all packages and make Doom -Emacs rolling release: -#+BEGIN_SRC elisp -(unpin! t) -#+END_SRC - -#+begin_quote -Unpinning all packages is discouraged because Doom's modules are designed -against the pinned versions of its packages. More volatile packages (like -lsp-mode, ein and org) change rapidly, and are likely to cause breakages if -unpinned. - -Instead, it's a better to selectively unpin packages, or repin them to the exact -commit you want. -#+end_quote - -*** Disabling packages -The ~package!~ macro possesses a ~:disable~ property: -#+BEGIN_SRC emacs-lisp -(package! irony :disable t) -(package! rtags :disable t) -#+END_SRC - -Once a package is disabled, ~use-package!~ and ~after!~ blocks for it will be -ignored, and the package is removed the next time you run ~bin/doom sync~. Use -this to disable Doom's packages that you don't want or need. - -There is also the ~disable-packages!~ macro for conveniently disabling multiple -packages: -#+BEGIN_SRC elisp -(disable-packages! irony rtags) -#+END_SRC - -#+begin_quote -*IMPORTANT:* Run ~bin/doom sync~ whenever you modify packages.el files to -ensure your changes take effect. -#+end_quote - -*** Changing a recipe for an included package -If a Doom module installs package X from one place, but you'd like to install it -from another (say, a superior fork), add a ~package!~ declaration for it in your -=DOOMDIR/packages.el=. Your private declarations always have precedence over -modules (even your own). -#+BEGIN_SRC elisp -;; in modules/editor/evil/packages.el -(package! evil) ; installs from MELPA - -;; in DOOMDIR/packages.el -(package! evil :recipe (:host github :repo "username/my-evil-fork")) -#+END_SRC - -To install a package only if a built-in package doesn't exist, use ~:built-in -'prefer~: -#+BEGIN_SRC elisp -(package! so-long :built-in 'prefer) -#+END_SRC - -#+begin_quote -*IMPORTANT:* Remember to run ~doom sync -u~ after changing recipes for existing -packages. At the time of writing, ~doom sync~ alone will not pick up on recipe -changes. -#+end_quote - -*** Using/loading local packages -Say you are developing an Emacs package locally and want to "install" it for -live testing. To do this specify a ~:local-repo~ in that package's recipe: -#+BEGIN_SRC elisp -(package! my-package - :recipe (:local-repo "/path/to/my/package")) - -;; Relative paths are expanded to ~/.emacs.d/.local/straight/repos/{local-repo} -;; or ~/.doom.d/{local-repo} -- the first that is found. -(package! my-package - :recipe (:local-repo "my/package")) ; looks for ~/.doom.d/my/package/my-package.el - -(package! my-package - :recipe (:local-repo "/path/to/my/package" - - ;; By default, the package manager grabs all *.el files at the root - ;; of the project and nothing else. To include other files, or - ;; accommodate unconventional project structures, specify what :files - ;; you want: - :files ("*.el" "src/lisp/*.el") - - ;; With this you can avoid having to run 'doom sync' every time you - ;; change the package. - :build (:not compile))) -#+END_SRC - -Alternatively, add the package's location to Emacs' ~load-path~. Do this if you -don't need/care for autoload cookies or byte-compilation: -#+BEGIN_SRC elisp -;; Doom has modified `use-package's `:load-path' to expand relative paths from -;; your DOOMDIR. e.g. ~/.doom.d/lisp/package -(use-package my-package - :load-path "lisp/package") - -;; or - -(add-load-path! "lisp/package") -#+END_SRC - -#+begin_quote -*IMPORTANT:* Remember to run ~doom sync~ to rebuild your package after you've -changed it, and to re-index any autoloads in it. -#+end_quote - -** Configuring Doom -*** Configuring packages -If your configuration needs are simple, the ~use-package!~, ~after!~, -~add-hook!~ and ~setq-hook!~ macros are your bread and butter. - -#+BEGIN_SRC emacs-lisp -;;; ~/.doom.d/config.el (example) -(setq doom-font (font-spec :family "Fira Mono" :size 12)) - -;; Takes a feature symbol or a library name (string) -(after! evil - (setq evil-magic nil)) - -;; Takes a major-mode, a quoted hook function or a list of either -(add-hook! python-mode - (setq python-shell-interpreter "bpython")) - -;; These are equivalent -(setq-hook! 'python-mode-hook python-indent-offset 2) -(setq-hook! python-mode python-indent-offset 2) - -(use-package! hl-todo - ;; if you omit :defer, :hook, :commands, or :after, then the package is loaded - ;; immediately. By using :hook here, the `hl-todo` package won't be loaded - ;; until prog-mode-hook is triggered (by activating a major mode derived from - ;; it, e.g. python-mode) - :hook (prog-mode . hl-todo-mode) - :init - ;; code here will run immediately - :config - ;; code here will run after the package is loaded - (setq hl-todo-highlight-punctuation ":")) -#+END_SRC - -For more flexibility, the ~use-package-hook!~ is another option, but should be -considered a last resort (because there is usually a better way). It allows you -to disable, append/prepend to and/or overwrite Doom's ~use-package!~ blocks. -These are powered by ~use-package~'s inject-hooks under the hood. - -~use-package-hook!~ *must be used before that package's ~use-package!~ block*. -Therefore it must be used from your private init.el file. - -#+BEGIN_SRC emacs-lisp -;;; ~/.doom.d/init.el (example) -;; If a :pre-init / :pre-config hook returns nil, it overwrites that package's -;; original :init / :config block. Exploit this to overwrite Doom's config. -(use-package-hook! doom-themes - :pre-config - (setq doom-neotree-file-icons t) - nil) - -;; ...otherwise, make sure they always return non-nil! -(use-package-hook! evil - :pre-init - (setq evil-magic nil) - t) - -;; `use-package-hook' also has :post-init and :post-config hooks -#+END_SRC - -*** Reloading your config -You may find it helpful to have your changes take effect immediately. For things -that don't require a complete restart of Doom Emacs (like changing your enabled -modules or installed packages), you can evaluate Emacs Lisp code on-the-fly. - -+ Evil users can use the =gr= operator to evaluate a segment of code. The return - value is displayed in the minibuffer or in a popup (if the result is large - enough to warrant one). - - =gr= works for most languages, but using it on Elisp is a special case; it's - executed within your current session of Emacs. You can use this to modify - Emacs' state on the fly. -+ Non-evil users can use =C-x C-e= to run ~eval-last-sexp~, as well as ~M-x - +eval/buffer-or-region~ (on =SPC c e=). -+ Another option is to open a scratch buffer with =SPC x=, change its major mode - (~M-x emacs-lisp-mode~), and use the above keys to evaluate your code. -+ An ielm REPL is available by pressing =SPC o r= - (~+eval/open-repl-other-window~). -+ There's also =M-:= or =SPC ;=, which invokes ~eval-expression~, which you can - use to run elisp code inline. - -While all this is helpful for reconfiguring your running Emacs session, it can -also be helpful for debugging. - -*** TODO Binding keys -+ define-key -+ global-set-key -+ map! -+ undefine-key! -+ define-key! - -** Writing your own modules -To create your own module you need only create a directory for it in -=~/.doom.d/modules/abc/xyz=, then add =:abc xyz= to your ~doom!~ block in -=~/.doom.d/init.el= to enable it. - -#+begin_quote -In this example, =:abc= is called the category and =xyz= is the name of the -module. Doom refers to modules in one of two formats: =:abc xyz= and =abc/xyz=. -#+end_quote - -If a private module possesses the same name as a built-in Doom module (say, -=:lang org=), it replaces the built-in module. Use this fact to rewrite modules -you don't agree with. - -Of course, an empty module isn't terribly useful, but it goes to show that nothing in a module is required. The typical module will have: - -+ A =packages.el= to declare all the packages it will install, -+ A =config.el= to configure and load those packages, -+ And, sometimes, an =autoload.el= to store that module's functions, to be - loaded when they are used. - -These are a few exceptional examples of a well-rounded module: -+ [[file:../modules/completion/company/README.org][:completion company]] - -The remainder of this guide will go over the technical details of a Doom module. - -*** File structure -Doom recognizes a handful of special file names, none of which are required for -a module to function. They are: - -#+begin_example -category/ - module/ - test/*.el - autoload/*.el - autoload.el - init.el - cli.el - config.el - packages.el - doctor.el -#+end_example - -**** =init.el= -This file is loaded early, before anything else, but after Doom core is loaded. -It is loaded in both interactive and non-interactive sessions (it's the only -file, besides =cli.el= that is loaded when the =bin/doom= starts up). - -Do: -+ Configure Emacs or perform setup/teardown operations that must be set early; - before other modules are (or this module is) loaded. -+ Reconfigure packages defined in Doom modules with ~use-package-hook!~ (as a - last resort, when ~after!~ and hooks aren't enough). -+ Configure behavior of =bin/doom= in a way that must also apply in - interactive sessions. - -Don't: -+ Configure packages with ~use-package!~ or ~after!~ from here -+ Preform expensive or error-prone operations; these files are evaluated - whenever =bin/doom= is used; a fatal error in this file can make Doom - unbootable (but not irreversibly). -+ Define new =bin/doom= commands here. That's what =cli.el= is for. - -**** =config.el= -The heart of every module. Code in this file should expect dependencies (in -=packages.el=) to be installed and available. Use it to load and configure its -packages. - -Do: -+ Use ~after!~ or ~use-package!~ to configure packages. - #+BEGIN_SRC emacs-lisp - ;; from modules/completion/company/config.el - (use-package! company ; `use-package!' is a thin wrapper around `use-package' - ; it is required that you use this in Doom's modules, - ; but not required to be used in your private config. - :commands (company-mode global-company-mode company-complete - company-complete-common company-manual-begin company-grab-line) - :config - (setq company-idle-delay nil - company-tooltip-limit 10 - company-dabbrev-downcase nil - company-dabbrev-ignore-case nil) - [...]) - #+END_SRC -+ Lazy load packages with ~use-package~'s ~:defer~ property. -+ Use the ~featurep!~ macro to make some configuration conditional based on the - state of another module or the presence of a flag. - -Don't: -+ Use ~package!~ -+ Install packages with =package.el= or ~use-package~'s ~:ensure~ property. Doom - has its own package manager. That's what =packages.el= is for. - -**** =packages.el= -This file is where package declarations belong. It's also a good place to look -if you want to see what packages a module manages (and where they are installed -from). - -Do: -+ Declare packages with the ~package!~ macro -+ Disable single packages with ~package!~'s ~:disable~ property or multiple - packages with the ~disable-packages!~ macro. -+ Use the ~featurep!~ macro to make packages conditional based on the state of - another module or the presence of a flag. - -Don't: -+ Configure packages here (definitely no ~use-package!~ or ~after!~ in here!). - This file is read in an isolated environment and will have no lasting effect. - The only exception is configuration targeting =straight.el=. -+ Perform expensive calculations. These files are read often and sometimes - multiple times. -+ Produce any side-effects, for the same reason. - -#+begin_quote -The "[[#package-management][Package Management]]" section goes over the ~package!~ macro and how to deal -with packages. -#+end_quote - -**** =autoload/*.el= OR =autoload.el= -These files are where you'll store functions that shouldn't be loaded until -they're needed and logic that should be autoloaded (evaluated very, very early -at startup). - -This is all made possible thanks to these autoload cookie: ~;;;###autoload~. -Placing this on top of a lisp form will do one of two things: - -1. Add a ~autoload~ call to Doom's autoload file (found in - =~/.emacs.d/.local/autoloads.el=, which is read very early in the startup - process). -2. Or copy that lisp form to Doom's autoload file verbatim (usually the case for - anything other than ~def*~ forms, like ~defun~ or ~defmacro~). - -Doom's autoload file is generated by scanning these files when you execute ~doom -sync~. - -For example: -#+BEGIN_SRC emacs-lisp -;; from modules/lang/org/autoload/org.el -;;;###autoload -(defun +org/toggle-checkbox () - (interactive) - [...]) - -;; from modules/lang/org/autoload/evil.el -;;;###autoload (autoload '+org:attach "lang/org/autoload/evil" nil t) -(evil-define-command +org:attach (&optional uri) - (interactive "") - [...]) -#+END_SRC - -**** =doctor.el= -When you execute ~doom doctor~, this file defines a series of tests for the -module. These should perform sanity checks on the environment, such as: - -+ Check if the module's dependencies are satisfied, -+ Warn if any of the enabled flags are incompatible, -+ Check if the system has any issues that may interfere with the operation of - this module. - -Use the ~warn!~, ~error!~ and ~explain!~ macros to communicate issues to the -user and, ideally, explain how to fix them. - -For example, the ~:lang cc~ module's doctor checks to see if the irony server is -installed: -#+BEGIN_SRC emacs-lisp -;; from lang/cc/doctor.el -(require 'irony) -(unless (file-directory-p irony-server-install-prefix) - (warn! "Irony server isn't installed. Run M-x irony-install-server")) -#+END_SRC - -**** TODO =cli.el= -This file is read when =bin/doom= starts up. Use it to define your own CLI -commands or reconfigure existing ones. - -**** TODO =test/**/test-*.el= -Doom's unit tests go here. More information on them to come... - -**** Additional files -Any files beyond the ones I have already named are not given special treatment. -They must be loaded manually to be loaded at all. In this way modules can be -organized in any way you wish. Still, there is one convention that has emerged -in Doom's community that you may choose to adopt: extra files in the root of the -module are prefixed with a plus, e.g. =+extra.el=. There is no syntactical or -functional significance to this convention. - -These can be loaded with the ~load!~ macro, which will load an elisp file -relative to the file it's used from. e.g. - -#+BEGIN_SRC emacs-lisp -;; Omitting the file extension allows Emacs to load the byte-compiled version, -;; if it is available: -(load! "+git") ; loads ./+git.el -#+END_SRC - -This can be useful for splitting up your configuration into multiple files, -saving you the hassle of creating multiple modules. - -*** Load order -A module's files have a precise load-order, which differs slightly depending on -what kind of session it is. Doom has three types of sessions: - -+ Interactive session :: the typical session you open when you intend to use - Emacs (e.g. for text editing). This loads the most, because you will likely be - using a lot of it. -+ Batch session :: this is a non-interactive session, loaded when you execute - Emacs commands on the command line with no UI, e.g. ~emacs --batch --eval - '(message "Hello world")'~. - - The expectation for these sessions is that it should quickly spin up, run the - command then quit, therefore very little is loaded in this session. -+ CLI session :: this is the same as a batch session /except/ it is what starts - up when you run any =bin/doom= command. - -With that out of the way, here is the load order of Doom's most important files: - -| File | Interactive | Batch | CLI | -|---------------------------------------------+-------------+-------+-----| -| ~/.emacs.d/early-init.el (Emacs 27+ only) | yes | no | no | -| ~/.emacs.d/init.el | yes | no | no | -| $DOOMDIR/init.el | yes | yes | yes | -| {~/.emacs.d,$DOOMDIR}/modules/*/*/init.el | yes | yes | yes | -| $DOOMDIR/cli.el | no | no | yes | -| {~/.emacs.d,$DOOMDIR}/modules/*/*/cli.el | no | no | yes | -| {~/.emacs.d,$DOOMDIR}/modules/*/*/config.el | yes | no | no | -| $DOOMDIR/config.el | yes | no | no | - -*** Flags -A module's flag is an arbitrary symbol. By convention, these symbols are -prefixed with a ~+~ or a ~-~ to denote the addition or removal of a feature, -respectively. There is no functional significance to this notation. - -A module may choose to interpret flags however it wishes, and can be tested for -using the ~featurep!~ macro: - -#+BEGIN_SRC elisp -;; Has the current module been enabled with the +my-feature flag? -(when (featurep! +my-feature) ...) - -;; It can be used to check the presence of flags in other modules: -(when (featurep! :lang python +lsp) ...) -#+END_SRC - -Use this fact to make aspects of a module conditional. e.g. Prevent company -plugins from loading if the =:completion company= module isn't enabled. - -*** Doom cookies -Autoload cookies were mentioned [[*=autoload/*.el= OR =autoload.el=][earlier]]. A couple more exist that are specific -to Doom Emacs. This section will go over what they do and how to use them. - -**** ~;;;###if~ -Any file in a module can have a ~;;;###if FORM~ cookie at or near the top of the -file (must be within the first 256 bytes of the file). =FORM= is evaluated to -determine whether or not to include this file for autoloads scanning (on ~doom -sync~) or byte-compilation (on ~doom compile~). - -i.e. if =FORM= returns ~nil~, Doom will neither index its ~;;;###autoload~ -cookies nor byte-compile the file. - -Use this to prevent errors that would occur if certain conditions aren't met. -For example, say =file.el= is using a certain function that won't be available -if the containing module wasn't enabled with a particular flag. We could safe -guard against this with: -#+BEGIN_SRC emacs-lisp -;;;###if (featurep! +particular-flag) -#+END_SRC - -This will prevent errors at compile time or if/when that file is loaded. - -Another example, this time contingent on =so-long= *not* being present: -#+BEGIN_SRC emacs-lisp -;;;###if (not (locate-library "so-long")) -#+END_SRC - -#+begin_quote -Keep in mind that =FORM= runs in a limited, non-interactive sub-session. I don't -recommend doing anything expensive or especially complicated in them. -#+end_quote - -**** ~;;;###package~ -This cookie exists solely to assist the ~doom/help-packages~ command. This -command shows you documentation about packages in the Emacs ecosystem, including -the ones that are installed. It also lists a) all the modules that install said -package and b) all the places it is configured. - -It accomplishes A by scanning for at ~package!~ declarations for that package, -but it accomplishes B by scanning for: - -+ ~after!~ calls -+ ~use-package!~ or ~use-package~ calls -+ and ~;;;###package X~ cookies, where X is the name of the package - -Use it to let ~doom/help-packages~ know where to find config for packages where -no ~after!~ or ~use-package!~ call is involved. - -**** ~;;;###autodef~ -An autodef is a special kind of autoloaded function (or macro) which Doom -guarantees will /always/ be defined, whether or not its containing module is -enabled (but will no-op if it is disabled). - -#+begin_quote -If the containing module is disabled the definition is replaced with a macro -that does not process its arguments, so it is a zero-cost abstraction. -#+end_quote - -You can browse the available autodefs in your current session with ~M-x -doom/help-autodefs~ (=SPC h d u= or =C-h d u=). - -An autodef cookie is used in exactly the same way as the autoload cookie: -#+BEGIN_SRC elisp -;;;###autodef -(defun set-something! (value) - ...) -#+END_SRC - -An example would be the ~set-company-backend!~ function that the =:completion -company= module exposes. It lets you register company completion backends with -certain major modes. For instance: -#+BEGIN_SRC emacs-lisp -(set-company-backend! 'python-mode '(company-anaconda)) -#+END_SRC - -And if =:completion company= is disabled, this call and its arguments are left -unprocessed and ignored. - -** Common mistakes when configuring Doom Emacs -Having helped many users configure Doom, I've spotted a few recurring oversights -that I will list here, in the hopes that it will help you avoid the same -mistakes: - -*** Packages are eagerly loaded -Using ~use-package!~ without a deferring keyword (one of: ~:defer :after -:commands :defer-incrementally :after-call~) will load the package immediately. -This causes other packages to be pulled in and loaded, which will compromise -many of Doom's startup optimizations. - -This is usually by accident. Choosing which keyword to use depends on the -needs of the package, so there is no simple answer to this. - -*** Manual package management -A lot of Emacs documentation and help will contain advice to install packages -with package.el's API (e.g. ~package-install~) or with use-package's ~:ensure~ -keyword). You are free to do this, if it is your preference, but otherwise, Doom -has its own package management system. - -Migrating ~use-package~ code to Doom is usually a case of removing the ~:ensure~ -keyword and adding a ~(package! PACKAGENAME)~ to =~/.doom.d/packages.el= (and -running ~doom sync~ to sync your config). - -*** Using ~org-babel-do-load-languages~ to load your babel packages -You don't need ~org-babel-do-load-languages~. Doom lazy loads babel packages -based on the language name in ~#+BEGIN_SRC~ blocks needed. As long as the babel -plugin is installed and the plugin is named after its language (e.g. -~#+BEGIN_SRC rust~ will load ~ob-rust~), you don't need to do anything else. - -There may be some special cases, however. Doom tries to handle a couple of them -(e.g. with ob-jupyter, ob-ipython and ob-async). If you are experiencing errors -while trying to use a certain language in org src blocks, check out the [[file:../modules/lang/org/README.org][:lang -org module documentation]] for details on how to add support for it. - -*** Using ~delete-trailing-whitespaces~ or ~whitespace-cleanup~ to manage leftover whitespace -#+BEGIN_SRC elisp -(add-hook 'after-save-hook #'delete-trailing-whitespace) -;; or -(add-hook 'after-save-hook #'whitespace-cleanup) -#+END_SRC - -These two lines are a common sight in Emacs configs, but they are unnecessary -for Doom Emacs. We already use the more sophisticated =ws-butler= to manage -extraneous whitespace. However, you might have the impression that it isn't -working. That's because =ws-butler= works in two unusual ways, meant to be less -imposing than its alternatives: - -1. It only cleans up trailing whitespace /on lines that you've touched/ (but - always strips newlines at EOF). - - Why do this? Because I believe file-wide reformatting should be a deliberate - act (and not blindly automated). If it is necessary, chances are you're - working on somebody else's project -- or with other people, but here, large - scale whitespace changes could cause problems or simply be rude. We don't - endorse PRs that are 1% contribution and 99% whitespace! - - However, if it's truly deliberate, ~M-x delete-trailing-whitespaces~ and ~M-x - whitespace-cleanup~ are available to be called =deliberately=, instead. - -2. =ws-butler= replaces trailing whitespace and newlines with *virtual* - whitespace. This is whitespace that only exists in the Emacs buffer, but - isn't actually written to the file. - - Why do this? Because you might have wanted to use that space for something in - your current editing session, and it would be inconvenient for the editor to - delete it before you got to it. - - If you use it, it's there. If you don't, it isn't written to the file. - -* Troubleshoot -When problems arise, you should be prepared to collect information in order to -solve them, or for the bug report you're about to write. Both Emacs and Doom -provide tools to make this easier. Here are a few things you can try, first: - -+ Investigate the =*Messages*= log for warnings or error messages. This log can - be opened with =SPC h e=, =C-h e= or =M-x view-echo-area-messages=. - -+ Look up errors/warnings [[file:faq.org::Common Issues][on the FAQ]] and [[https://github.com/hlissner/doom-emacs/issues][Doom's issue tracker]]. It is possible - that a solution for your issue already exists. The FAQ can be searched from - inside Doom with =SPC h d f= (or =C-h d f= for non-evil users). - -+ Run ~bin/doom doctor~ on the command line to diagnose common issues with your - environment and config. It will suggest solutions for them as well. - -+ ~bin/doom clean~ will ensure the problem isn't stale bytecode in your private - config or Doom core. If you haven't used ~bin/doom compile~, there's no need - to do this. - -+ ~bin/doom sync~ will ensure the problem isn't missing packages or outdated - autoloads files - -+ ~bin/doom build~ will ensure the problem isn't stale package bytecode or - broken symlinks. - -+ ~bin/doom update~ will ensure that your packages are up-to-date, eliminating - issues that originate from upstream. - -+ If you happen to know what module(s) are relevant to your issue, check their - documentation (press = h d m= to jump to a module's documentation). Your - issue may be documented. - -+ If possible, see if the issue can be reproduced in vanilla Emacs (Emacs - without Doom) and/or vanilla Doom (Doom without your private config). [[#testing-in-dooms-sandbox][Doom's - sandbox can help you check]]. - -+ Ask for help on [[https://discord.gg/qvGgnVx][our Discord server]]. It is the quickest way to get help, - sometimes straight from Doom's maintainer, who is very active there. - -If none of these things have helped you, then it's time to open a bug report. -See "[[file:contributing.org::*Reporting issues][Reporting Issues]]" in the [[file:contributing.org][contributing guidelines]] on how to file an -effective bug report. - -** Looking up documentation and state from within Emacs -... - -*** Variables, functions, faces, etc. -Emacs is a Lisp interpreter whose state you can access on-the-fly with tools -provided to you by Emacs itself. They're available on the =SPC h= prefix by -default. Use them to debug your sessions. - -Here are some of the more important ones: - -+ ~describe-variable~ (=SPC h v=) -+ ~describe-function~ (=SPC h f=) -+ ~describe-face~ (=SPC h F=) -+ ~describe-bindings~ (=SPC h b=) -+ ~describe-key~ (=SPC h k=) -+ ~describe-char~ (=SPC h '=) -+ ~find-library~ (=SPC h P=) - -You can also evaluate code with ~eval-expression~ (=M-;= or =SPC ;=). - -*** TODO For Doom Modules, packages, autodefs, etc. -+ ~doom/open-news~ (=SPC h n=) :: - ... -+ ~doom/help~ (=SPC h d h=) :: - Open the index of Doom's manual. -+ ~doom/help-modules~ (=SPC h d m=) :: - Jumps to a module's documentation. -+ ~doom/help-autodefs~ (=SPC h u=) :: - Jumps to the documentation for an autodef function/macro. These are special - functions that are always defined, whether or not their containing modules - are enabled. -+ ~doom/help-packages~ (=SPC h p=) :: - Look up packages that are installed, by whom (what modules) and where jump - to all the places it is being configured. -+ ~doom/info~ :: - ... - -** How to extract a backtrace from an error -If you encounter an error while using Doom Emacs, you're probably about to head -off and file a bug report (or request help on [[https://discord.gg/qvGgnVx][our Discord server]]). Before you -do, please generate a backtrace to include with it. - -To do so you must enable ~debug-on-error~ then recreate the error. - -*** Enabling ~debug-on-error~ -There are three ways to enable ~debug-on-error~: - -1. Start Emacs with ~emacs --debug-init~. Use this for errors that occur at - startup. -2. Evil users can press =SPC h d d= and non-evil users can press =C-h d d=. -3. If the above don't work, there's always: ~M-x toggle-debug-on-error~ - -Now that ~debug-on-error~ is on, recreate the error. A window should pop up with -a backtrace. - -*** A backtrace from ~bin/doom~ -If the error you've encountered is emitted from ~bin/doom~, you can re-run the -same command with the ~-d~ or ~--debug~ switches to force it to emit a backtrace -when an error occurs. The ~DEBUG~ environment variable will work to. - -#+BEGIN_SRC sh -doom -d sync -doom --debug install -DEBUG=1 doom update -#+END_SRC - -#+BEGIN_QUOTE -Note: switch order is important. ~-d~ / ~--debug~ /must/ come right after ~doom~ -and before the subcommand. This will be fixed eventually. -#+END_QUOTE - -** Evaluating Elisp on-the-fly -Often, you may find it helpful for debugging to evaluate some Emacs Lisp. Here -are couple things you can do: - -+ Use =M-:= (bound to ~eval-expression~), -+ =SPC x= will open a scratch buffer. ~M-x emacs-lisp-mode~ will change it to - the appropriate major mode, then use ~+eval:region~ (=gr=) and ~+eval/buffer~ - (=gR=) to evaluate code, - -** How to determine the origin of a bug -** Testing in Doom's sandbox -"The sandbox" is one of Doom Emacs' features; it is a test bed for running elisp -in a fresh instance of Emacs with varying amounts of Doom loaded (none at all, -all of it, or somewhere in between). This can be helpful for isolating bugs to -determine who you should report a bug to. - -If you can recreate a bug in vanilla Emacs then it should be reported to the -developers of the relevant packages or, perhaps, the Emacs devs themselves. - -Otherwise, it is best to bring it up on the Doom Emacs issue list, rather than -confusing and inundating the Emacs community with Doom-specific issues. - -*** Opening the sandbox -There are three common ways to access the sandbox: - -+ =SPC h E= (for evil users) -+ =C-h E= (for non-evil users) -+ ~M-x doom/sandbox~ - -Doing any of the above will pop up a ~*doom:sandbox*~ window. What you enter -into this buffer will be executed in the new instance of Emacs when you decide -to launch it. - -*** Launching the sandbox -You have four options when it comes to launching the sandbox: - -- =C-c C-c= :: This launches "vanilla Emacs". Vanilla means nothing is loaded; - purely Emacs and nothing else. If you can reproduce an error here, then the - issue likely lies in the plugin(s) you are testing or in Emacs itself. -- =C-c C-d= :: This launches "vanilla Doom", which is vanilla Emacs plus Doom's - core. This does not load your private config, nor any of Doom's (or your) - modules. -- =C-c C-p= :: This launches "vanilla Doom+". That is, Doom core plus the - modules that you have specified in the ~doom!~ block of your private config - (in =~/.doom.d/init.el=). This *does not* load your private config, however. -- =C-c C-f= :: This launches "full Doom". It loads Doom's core, your enabled - modules, and your private config. This instance should be identical to the - instance you launched it from. - -#+BEGIN_QUOTE -All new instances will inherit your ~load-path~ so you can access any packages -you have installed. -#+END_QUOTE -*** Testing packages in the sandbox -Instances of Emacs launched from the sandbox have inherited your ~load-path~. -This means you can load packages -- even in Vanilla Emacs -- without worrying -about installing or setting them up. Just ~(require PACKAGE)~ and launch the -sandbox. e.g. - -#+BEGIN_SRC elisp -(require 'magit) -(find-file "~/some/file/in/a/repo") -(call-interactively #'magit-status) -#+END_SRC - -** TODO Bisecting your private config -** TODO Bisecting Doom Emacs diff --git a/docs/modules.org b/docs/modules.org deleted file mode 100644 index 7eddea11e..000000000 --- a/docs/modules.org +++ /dev/null @@ -1,226 +0,0 @@ -#+TITLE: Module Index -#+STARTUP: nofold - -Functionality in Doom is divided into collections of code called modules (Γ  la -Spacemacs' layers). A module is a bundle of packages, configuration and -commands, organized into a unit that can be enabled or disabled by adding or -removing them from your ~doom!~ block in =$DOOMDIR/init.el=. - -* Table of Contents :TOC: -- [[#app][:app]] -- [[#checkers][:checkers]] -- [[#completion][:completion]] -- [[#config][:config]] -- [[#editor][:editor]] -- [[#emacs][:emacs]] -- [[#email][:email]] -- [[#input][:input]] -- [[#lang][:lang]] -- [[#os][:os]] -- [[#term][:term]] -- [[#tools][:tools]] -- [[#ui][:ui]] - -* :app -Application modules are complex and opinionated modules that transform Emacs -toward a specific purpose. They may have additional dependencies and *should be -loaded last*, before =:config= modules. - -+ [[file:../modules/app/calendar/README.org][calendar]] - TODO -+ [[file:../modules/app/emms/README.org][emms]] - TODO -+ [[file:../modules/app/everywhere/README.org][everywhere]] - TODO -+ [[file:../modules/app/irc/README.org][irc]] - how neckbeards socialize -+ [[file:../modules/app/rss/README.org][rss]] =+org= - an RSS client in Emacs -+ [[file:../modules/app/twitter/README.org][twitter]] - A twitter client for Emacs - -* :checkers -+ syntax =+childframe= - Live error/warning highlights -+ [[file:../modules/checkers/spell/README.org][spell]] =+aspell +flyspell +enchant +everywhere +hunspell= - Spell checking -+ [[file:../modules/checkers/grammar/README.org][grammar]] - TODO - -* :completion -Modules that provide new interfaces or frameworks for completion, including code -completion. - -+ [[file:../modules/completion/company/README.org][company]] =+childframe +tng= - The ultimate code completion backend -+ helm =+fuzzy +childframe= - *Another* search engine for love and life -+ ido - The /other/ *other* search engine for love and life -+ [[file:../modules/completion/ivy/README.org][ivy]] =+fuzzy +prescient +childframe +icons= - /The/ search engine for love and life -+ [[file:../modules/completion/vertico/README.org][vertico]] =+icons= - The search engine of the future - -* :config -Modules that configure Emacs one way or another, or focus on making it easier -for you to customize it yourself. It is best to load these last. - -+ [[file:../modules/config/literate/README.org][literate]] - For users with literate configs. This will tangle+compile a - config.org in your ~doom-private-dir~ when it changes. -+ [[file:../modules/config/default/README.org][default]] =+bindings +smartparens= - The default module sets reasonable defaults - for Emacs. It also provides a Spacemacs-inspired keybinding scheme and a - smartparens config. Use it as a reference for your own modules. - -* :editor -Modules that affect and augment your ability to manipulate or insert text. - -+ [[file:../modules/editor/evil/README.org][evil]] =+everywhere= - transforms Emacs into Vim -+ [[file:../modules/editor/file-templates/README.org][file-templates]] - Auto-inserted templates in blank new files -+ [[file:../modules/editor/fold/README.org][fold]] - universal code folding -+ format =+onsave= - TODO -+ god - TODO -+ [[file:../modules/editor/lispy/README.org][lispy]] - TODO -+ multiple-cursors - TODO -+ [[file:../modules/editor/objed/README.org][objed]] =+manual= - TODO -+ [[file:../modules/editor/parinfer/README.org][parinfer]] - TODO -+ rotate-text - TODO -+ [[file:../modules/editor/snippets/README.org][snippets]] - Snippet expansion for lazy typists -+ [[file:../modules/editor/word-wrap/README.org][word-wrap]] - soft wrapping with language-aware indent - -* :emacs -Modules that reconfigure or augment packages or features built into Emacs. - -+ [[file:../modules/emacs/dired/README.org][dired]] =+ranger +icons= - TODO -+ electric - TODO -+ [[file:../modules/emacs/ibuffer/README.org][ibuffer]] =+icons= - TODO -+ [[file:../modules/emacs/undo/README.org][undo]] =+tree= - A smarter, more intuitive & persistent undo history -+ [[file:../modules/emacs/vc/README.org][vc]] - TODO - -* :email -+ [[file:../modules/email/mu4e/README.org][mu4e]] =+org +gmail= - TODO -+ [[file:../modules/email/notmuch/README.org][notmuch]] - TODO -+ wanderlust =+gmail= - TODO - -* :input -+ [[file:../modules/input/bidi/README.org][bidi]] - (tfel ot) thgir etirw uoy gnipleh -+ [[file:../modules/input/chinese/README.org][chinese]] - TODO -+ [[file:../modules/input/japanese/README.org][japanese]] - TODO -+ [[file:../modules/input/layout/README.org][layout]] =+azerty +bepo= - TODO - -* :lang -Modules that bring support for a language or group of languages to Emacs. - -+ [[file:../modules/lang/agda/README.org][agda]] =+local= - TODO -+ [[file:../modules/lang/beancount/README.org][beancount]] =+lsp= - TODO -+ [[file:../modules/lang/cc/README.org][cc]] =+lsp= - TODO -+ [[file:../modules/lang/clojure/README.org][clojure]] =+lsp= - TODO -+ common-lisp - TODO -+ [[file:../modules/lang/coq/README.org][coq]] - TODO -+ [[file:../modules/lang/crystal/README.org][crystal]] - TODO -+ [[file:../modules/lang/csharp/README.org][csharp]] =+lsp +unity= - TODO -+ [[file:../modules/lang/dart/README.org][dart]] =+lsp +flutter= -+ data - TODO -+ [[file:../modules/lang/elixir/README.org][elixir]] =+lsp= - TODO -+ elm =+lsp= - TODO -+ [[file:../modules/lang/emacs-lisp/README.org][emacs-lisp]] - TODO -+ [[file:../modules/lang/erlang/README.org][erlang]] =+lsp= - TODO -+ [[file:../modules/lang/ess/README.org][ess]] =+lsp= - TODO -+ [[file:../modules/lang/factor/README.org][factor]] - TODO -+ [[file:../modules/lang/faust/README.org][faust]] - TODO -+ [[file:../modules/lang/fsharp/README.org][fsharp]] =+lsp= - TODO -+ [[file:../modules/lang/fstar/README.org][fstar]] - F* support -+ [[file:../modules/lang/gdscript/README.org][gdscript]] =+lsp= - TODO -+ [[file:../modules/lang/go/README.org][go]] =+lsp= - TODO -+ [[file:../modules/lang/haskell/README.org][haskell]] =+lsp= - TODO -+ hy - TODO -+ [[file:../modules/lang/idris/README.org][idris]] - TODO -+ java =+meghanada +eclim +lsp= - TODO -+ [[file:../modules/lang/javascript/README.org][javascript]] =+lsp= - JavaScript, TypeScript, and CoffeeScript support -+ [[file:../modules/lang/json/README.org][json]] =+lsp= - TODO -+ [[file:../modules/lang/julia/README.org][julia]] =+lsp= - TODO -+ [[file:../modules/lang/kotlin/README.org][kotlin]] =+lsp= - TODO -+ [[file:../modules/lang/latex/README.org][latex]] =+latexmk +cdlatex +fold +lsp= - TODO -+ lean - TODO -+ [[file:../modules/lang/ledger/README.org][ledger]] - TODO -+ [[file:../modules/lang/lua/README.org][lua]] =+fennel +moonscript= - TODO -+ [[file:../modules/lang/markdown/README.org][markdown]] =+grip= - TODO -+ [[file:../modules/lang/nim/README.org][nim]] - TODO -+ [[file:../modules/lang/nix/README.org][nix]] - TODO -+ [[file:../modules/lang/ocaml/README.org][ocaml]] =+lsp= - TODO -+ [[file:../modules/lang/org/README.org][org]] =+brain +dragndrop +gnuplot +hugo +ipython +journal +jupyter +noter +pandoc +pomodoro +present +pretty +roam= - TODO -+ [[file:../modules/lang/php/README.org][php]] =+hack +lsp= - TODO -+ plantuml - TODO -+ purescript =+lsp= - TODO -+ [[file:../modules/lang/python/README.org][python]] =+cython +lsp +pyright +pyenv +conda +poetry= - TODO -+ qt - TODO -+ [[file:../modules/lang/racket/README.org][racket]] =+lsp +xp= - TODO -+ [[file:../modules/lang/raku/README.org][raku]] - TODO -+ [[file:../modules/lang/rest/README.org][rest]] - TODO -+ rst - TODO -+ [[file:../modules/lang/ruby/README.org][ruby]] =+lsp +rvm +rbenv +rails +chruby= -+ [[file:../modules/lang/rust/README.org][rust]] =+lsp= - TODO -+ [[file:../modules/lang/scala/README.org][scala]] =+lsp= - TODO -+ [[file:../modules/lang/scheme/README.org][scheme]] =+chez +chibi +chicken +gambit +gauche +guile +kawa +mit +racket= - TODO -+ [[file:../modules/lang/sh/README.org][sh]] =+fish +lsp +powershell= - TODO -+ [[file:../modules/lang/sml/README.org][sml]] - TODO -+ [[file:../modules/lang/solidity/README.org][solidity]] - TODO -+ swift =+lsp= - TODO -+ terra - TODO -+ web =+lsp= - HTML and CSS (SCSS/SASS/LESS/Stylus) support. -+ [[file:../modules/lang/yaml/README.org][yaml]] =+lsp= - TODO -+ [[file:../modules/lang/zig/README.org][zig]] =+lsp= - Zig support. - - -* :os -Modules to improve integration into your OS, system, or devices. - -+ [[file:../modules/os/macos/README.org][macos]] - Improve Emacs' compatibility with macOS -+ [[file:../modules/os/tty/README.org][tty]] =+osc= - Improves the terminal Emacs experience. - -* :term -Modules that offer terminal emulation. - -+ [[file:../modules/term/eshell/README.org][eshell]] - TODO -+ shell - TODO -+ term - TODO -+ [[file:../modules/term/vterm/README.org][vterm]] - TODO - -* :tools -Small modules that give Emacs access to external tools & services. - -+ ansible - TODO -+ debugger =+lsp= - A (nigh-)universal debugger in Emacs -+ [[file:../modules/tools/direnv/README.org][direnv]] - TODO -+ [[file:../modules/tools/docker/README.org][docker]] =+lsp= - TODO -+ [[file:../modules/tools/editorconfig/README.org][editorconfig]] - TODO -+ [[file:../modules/tools/ein/README.org][ein]] - TODO -+ [[file:../modules/tools/eval/README.org][eval]] =+overlay= - REPL & code evaluation support for a variety of languages -+ gist - TODO -+ [[file:../modules/tools/lookup/README.org][lookup]] =+dictionary +docsets +offline= - Universal jump-to & documentation lookup - backend -+ [[file:../modules/tools/lsp/README.org][lsp]] =+peek +eglot= - Installation and configuration of language server protocol client (lsp-mode or eglot) -+ [[file:../modules/tools/magit/README.org][magit]] =+forge= - TODO -+ make - TODO -+ [[file:../modules/tools/pass/README.org][pass]] =+auth= - TODO -+ [[file:../modules/tools/pdf/README.org][pdf]] - TODO -+ prodigy - TODO -+ [[file:../modules/tools/rgb/README.org][rgb]] - TODO -+ [[file:../modules/tools/taskrunner/README.org][taskrunner]] - TODO -+ [[file:../modules/tools/terraform/README.org][terraform]] - TODO -+ tmux - TODO -+ [[file:../modules/tools/tree-sitter/README.org][tree-sitter]] - syntax and parsing, sitting in a tree... -+ [[file:../modules/tools/upload/README.org][upload]] - TODO - -* :ui -Aesthetic modules that affect the Emacs interface or user experience. - -+ [[file:../modules/ui/deft/README.org][deft]] - TODO -+ [[file:../modules/ui/doom/README.org][doom]] - TODO -+ [[file:../modules/ui/doom-dashboard/README.org][doom-dashboard]] - TODO -+ [[file:../modules/ui/doom-quit/README.org][doom-quit]] - TODO -+ [[file:../modules/ui/emoji/README.org][emoji]] =+ascii +github +unicode= - Adds emoji support to Emacs -+ [[file:../modules/ui/hl-todo/README.org][hl-todo]] - TODO -+ [[file:../modules/ui/hydra/README.org][hydra]] - TODO -+ indent-guides - TODO -+ [[file:../modules/ui/ligatures/README.org][ligatures]] =+extra +fira +hasklig +iosevka +pragmata-pro= - Ligature support for Emacs -+ [[file:../modules/ui/minimap/README.org][minimap]] - TODO -+ [[file:../modules/ui/modeline/README.org][modeline]] =+light= - TODO -+ [[file:../modules/ui/nav-flash/README.org][nav-flash]] - TODO -+ [[file:../modules/ui/neotree/README.org][neotree]] - TODO -+ [[file:../modules/ui/ophints/README.org][ophints]] - TODO -+ [[file:../modules/ui/popup/README.org][popup]] =+all +defaults= - Makes temporary/disposable windows less intrusive -+ [[file:../modules/ui/tabs/README.org][tabs]] - TODO -+ [[file:../modules/ui/treemacs/README.org][treemacs]] - =+lsp= - A tree layout file explorer for Emacs -+ [[file:../modules/ui/unicode/README.org][unicode]] - TODO -+ vc-gutter - TODO -+ vi-tilde-fringe - TODO -+ [[file:../modules/ui/window-select/README.org][window-select]] =+switch-window +numbers= - TODO -+ [[file:../modules/ui/workspaces/README.org][workspaces]] - Isolated workspaces -+ [[file:../modules/ui/zen/README.org][zen]] - Distraction-free coding (or writing) diff --git a/lisp/doom-editor.el b/lisp/doom-editor.el index f8d7c0675..e5989b864 100644 --- a/lisp/doom-editor.el +++ b/lisp/doom-editor.el @@ -1,7 +1,7 @@ ;;; doom-editor.el -*- lexical-binding: t; -*- (defvar doom-detect-indentation-excluded-modes - '(fundamental-mode pascal-mode so-long-mode) + '(fundamental-mode pascal-mode so-long-mode doom-docs-org-mode) "A list of major modes in which indentation should be automatically detected.") diff --git a/lisp/lib/docs.el b/lisp/lib/docs.el new file mode 100644 index 000000000..991e3f7d2 --- /dev/null +++ b/lisp/lib/docs.el @@ -0,0 +1,624 @@ +;;; core/lib/docs.el -- a reader mode for Doom's Org docs -*- lexical-binding: t; -*- +;;; Commentary: +;;; Code: + +(defvar doom-docs-header-alist + `(("/docs/index\\.org$" + (left ("β†– FAQ" . "doom-faq:"))) + (("/docs/[^/]+\\.org$" "/modules/README\\.org$") + (left ("← Back to index" . "doom-index:"))) + ("/modules/[^/]+/README\\.org$" + (left ("← Back to module index" . "doom-module-index:"))) + ("/modules/[^/]+/[^/]+/README\\.org$" + (left ("← Back to module index" . "doom-module-index:")) + (right ("β†– History" + . ,(lambda (file) + (cl-destructuring-bind (category . module) (doom-module-from-path file) + (format "doom-module-history:%s/%s" (doom-keyword-name category) module)))) + ("! Issues" + . ,(lambda (file) + (cl-destructuring-bind (category . module) (doom-module-from-path file) + (format "doom-module-issues::%s %s" category module))))))) + "TODO") + +(defvar doom-docs-header-common-alist + `(("Β± Suggest edits" . "doom-suggest-edit:") + ("? Help" + . ,(lambda (_file) + (let ((title (cadar (org-collect-keywords '("TITLE"))))) + (cond ((equal title "Changelog") "doom-help-changelog:") + ((string-prefix-p ":" title) "doom-help-modules:") + ("doom-help:")))))) + "TODO") + + +;; +;;; `doom-docs-mode' + +(defun doom-docs--display-header-h () + "Show header line in Doom documentation." + (let ((beg (point-min)) + end) + (org-with-wide-buffer + (goto-char beg) + (when (looking-at-p "^# -\\*- ") + (goto-char (line-beginning-position 2)) + (setq beg (point))) + (when (looking-at-p org-drawer-regexp) + (re-search-forward org-drawer-regexp nil t 2) + (goto-char (setq beg (1+ (line-end-position))))) + (with-silent-modifications + (let ((inhibit-modification-hooks nil) + (menu (cl-loop for (regexp . rules) in doom-docs-header-alist + if (seq-find (doom-rpartial #'string-match-p (buffer-file-name)) + (ensure-list regexp)) + return rules))) + (when (re-search-forward "^-\\{80\\}" 512 t) + (delete-region beg (1+ (line-end-position)))) + (when (and menu doom-docs-mode) + (let* ((fn + (lambda (menu) + (cl-destructuring-bind (icon . label) + (split-string (car menu) " ") + (if (cdr menu) + (format "%s [[%s][%s]]" + icon + (cond ((functionp (cdr menu)) + (funcall (cdr menu) (buffer-file-name))) + ((file-name-absolute-p (cdr menu)) + (concat "file:" + (file-relative-name (file-truename (cdr menu))))) + ((cdr menu))) + (string-join label " ")) + (format "%s+ %s+" icon (string-join label " ")))))) + (lenfn + (lambda (link) + (length (replace-regexp-in-string org-link-any-re "\\3" link)))) + (sep " ") + (lhs (mapconcat fn (alist-get 'left menu) sep)) + (rhs (mapconcat fn (append (alist-get 'right menu) + doom-docs-header-common-alist) + sep)) + (llen (funcall lenfn lhs)) + (rlen (funcall lenfn rhs)) + (pad (max 0 (- 80 llen rlen)))) + (insert lhs + (if (zerop rlen) "" + (format "%s%s" (make-string pad 32) rhs)) + "\n" (make-string 80 ?-) "\n"))))) + (org-element-cache-refresh (point-min))))) + +(defun doom-docs--hide-meta-h () + "Hide all meta or comment lines." + (org-with-wide-buffer + (goto-char (point-min)) + (save-match-data + (let ((case-fold-search t)) + (while (re-search-forward "^[ \t]*\\#" nil t) + (catch 'abort + (org-fold-core-region + (line-beginning-position) + (cond ((looking-at "+\\(?:title\\|subtitle\\): +") + (match-end 0)) + ((looking-at "+\\(?:created\\|since\\|author\\|email\\|date\\): +") + (throw 'abort nil)) + ((or (eq (char-after) ?\s) + (looking-at "+\\(begin\\|end\\)_comment")) + (line-beginning-position 2)) + ((looking-at "+\\(?:begin\\|end\\)_\\([^ \n]+\\)") + (line-end-position)) + ((line-beginning-position 2))) + doom-docs-mode 'doom-doc-hidden))))))) + +(defun doom-docs--hide-drawers-h () + "Hide all property drawers." + (org-with-wide-buffer + (goto-char (point-min)) + (while (re-search-forward org-drawer-regexp nil t) + (let ((beg (max (point-min) (1- (match-beginning 0)))) + (end (re-search-forward org-drawer-regexp nil t))) + (unless (org-current-level) + (cl-incf end)) + (org-fold-core-region beg end doom-docs-mode 'doom-doc-hidden))))) + +(defun doom-docs--hide-tags-h () + "Hide tags in org headings." + (org-with-wide-buffer + (goto-char (point-min)) + (while (re-search-forward org-heading-regexp nil t) + (when-let (tags (org-get-tags nil t)) + (when (or (member "noorg" tags) + (member "unfold" tags)) + ;; prevent `org-ellipsis' around hidden regions + (org-show-entry)) + (if (member "noorg" tags) + (org-fold-core-region (line-end-position 0) + (save-excursion + (org-end-of-subtree t) + (forward-line 1) + (if (and (bolp) (eolp)) + (line-beginning-position) + (line-end-position 0))) + doom-docs-mode 'doom-doc-hidden) + (org-fold-core-region (save-excursion + (goto-char (line-beginning-position)) + (re-search-forward " +:[^ ]" (line-end-position)) + (match-beginning 0)) + (line-end-position) + doom-docs-mode 'doom-doc-hidden)))))) + +(defun doom-docs--hide-stars-h () + "Update invisible property to VISIBILITY for markers in the current buffer." + (org-with-wide-buffer + (goto-char (point-min)) + (with-silent-modifications + (while (re-search-forward "^\\(\\*[ \t]\\|\\*\\*+\\)" nil t) + (org-fold-core-region (match-beginning 0) + (match-end 0) + doom-docs-mode + 'doom-doc-hidden))))) + +(defvar doom-docs--babel-cache nil) +(defun doom-docs--hide-src-blocks-h () + "Hide babel blocks (and/or their results) depending on their :exports arg." + (org-with-wide-buffer + (let ((inhibit-read-only t)) + (goto-char (point-min)) + (make-local-variable 'doom-docs--babel-cache) + (while (re-search-forward org-babel-src-block-regexp nil t) + (let* ((beg (match-beginning 0)) + (end (save-excursion (goto-char (match-end 0)) + (skip-chars-forward "\n") + (point))) + (exports + (save-excursion + (goto-char beg) + (and (re-search-forward " :exports \\([^ \n]+\\)" (line-end-position) t) + (match-string-no-properties 1)))) + (results (org-babel-where-is-src-block-result))) + (save-excursion + (when (and (if (stringp exports) + (member exports '("results" "both")) + org-export-use-babel) + (not results) + doom-docs-mode) + (cl-pushnew beg doom-docs--babel-cache) + (quiet! (org-babel-execute-src-block)) + (setq results (org-babel-where-is-src-block-result)) + (org-element-cache-refresh beg) + (restore-buffer-modified-p nil))) + (save-excursion + (when results + (when (member exports '("code" "both" "t")) + (setq beg results)) + (when (member exports '("none" "code")) + (setq end (progn (goto-char results) + (goto-char (org-babel-result-end)) + (skip-chars-forward "\n") + (point)))))) + (unless (member exports '(nil "both" "code" "t")) + (org-fold-core-region beg end doom-docs-mode 'doom-doc-hidden)))) + (unless doom-docs-mode + (save-excursion + (dolist (pos doom-docs--babel-cache) + (goto-char pos) + (org-babel-remove-result) + (org-element-cache-refresh pos)) + (kill-local-variable 'doom-docs--babel-cache) + (restore-buffer-modified-p nil)))))) + +(defvar doom-docs--macro-cache nil) +(defun doom-docs--expand-macros-h () + "Expand {{{macros}}} with their value." + (org-with-wide-buffer + (goto-char (point-min)) + (make-local-variable 'doom-docs--macro-cache) + (while (re-search-forward "{{{[^}]+}}}" nil t) + (with-silent-modifications + (if doom-docs-mode + (when-let* ((element (org-element-context)) + (key (org-element-property :key element)) + (cachekey (org-element-property :value element)) + (template (cdr (assoc-string key org-macro-templates t)))) + (let ((value (or (cdr (assoc-string cachekey doom-docs--macro-cache)) + (setf (alist-get cachekey doom-docs--macro-cache nil nil 'equal) + (org-macro-expand element org-macro-templates))))) + (add-text-properties (match-beginning 0) + (match-end 0) + `(display ,value)))) + (remove-text-properties (match-beginning 0) + (match-end 0) + '(display)))) + (org-element-cache-refresh (point))))) + +(defvar doom-docs-mode-alist + '((flyspell-mode . -1) + (spell-fu-mode . -1) + (visual-line-mode . -1) + (mixed-pitch-mode . -1) + (variable-pitch-mode . -1)) + "An alist of minor modes to activate or deactivate in `doom-docs-mode'. + +The CAR is the minor mode symbol, and CDR should be either +1 or -1, +depending.") + +(defvar doom-docs--initial-values nil) +(defvar doom-docs--cookies nil) +;;;###autoload +(define-minor-mode doom-docs-mode + "Hides metadata, tags, & drawers and activates all org-mode pretiffications. +This primes `org-mode' for reading." + :lighter " Doom Docs" + :after-hook (org-restart-font-lock) + (unless (derived-mode-p 'org-mode) + (user-error "Not an org mode buffer")) + (org-fold-add-folding-spec + 'doom-doc-hidden '(:visible nil + :alias (hidden) + :isearch-open nil + :font-lock-skip t)) + (mapc (lambda (sym) + (if doom-docs-mode + (set (make-local-variable sym) t) + (kill-local-variable sym))) + `(org-pretty-entities + org-hide-emphasis-markers + org-hide-macro-markers)) + (when doom-docs-mode + (make-local-variable 'doom-docs--initial-values)) + (mapc (lambda! ((face . plist)) + (if doom-docs-mode + (push (apply #'face-remap-add-relative face plist) doom-docs--cookies) + (mapc #'face-remap-remove-relative doom-docs--cookies))) + '((org-document-title :weight bold :height 1.4) + (org-document-info :weight normal :height 1.15))) + (mapc (lambda! ((mode . state)) + (if doom-docs-mode + (if (and (boundp mode) (symbol-value mode)) + (unless (> state 0) + (setf (alist-get mode doom-docs--initial-values) t) + (funcall mode -1)) + (unless (< state 0) + (setf (alist-get mode doom-docs--initial-values) nil) + (funcall mode +1))) + (when-let (old-val (assq mode doom-docs--initial-values)) + (funcall mode (if old-val +1 -1))))) + doom-docs-mode-alist) + (unless doom-docs-mode + (kill-local-variable 'doom-docs--initial-values))) + +(add-hook! 'doom-docs-mode-hook + #'doom-docs--display-header-h + #'doom-docs--hide-meta-h + #'doom-docs--hide-tags-h + #'doom-docs--hide-drawers-h + #'doom-docs--hide-stars-h + #'doom-docs--expand-macros-h + #'doom-docs--hide-src-blocks-h) + +(defun doom-docs--toggle-read-only-h () + (doom-docs-mode (if buffer-read-only +1 -1))) + + +(defvar doom-docs--id-locations nil) +(defvar doom-docs--id-files nil) +;;;###autoload +(defun doom/reload-docs (&optional force) + "Reload the ID locations in Doom's documentation and open docs buffers." + (interactive (list 'interactive)) + (with-temp-buffer + (let ((org-id-locations-file + (doom-path (file-truename doom-cache-dir) "doom-docs-org-ids")) + (org-id-track-globally t) + org-agenda-files + org-id-extra-files + org-id-files + org-id-locations + org-id-extra-files + (org-inhibit-startup t) + org-mode-hook) + (if force + (org-id-update-id-locations + (doom-files-in (list doom-docs-dir doom-modules-dir) + :match "/[^.].+\\.org$")) + (org-id-locations-load)) + (setq doom-docs--id-files org-id-files + doom-docs--id-locations org-id-locations))) + (dolist (buf (doom-buffers-in-mode 'doom-docs-org-mode)) + (with-current-buffer buf + (setq-local org-id-files doom-docs--id-files + org-id-locations doom-docs--id-locations)))) + + +;; +;;; `doom-docs-org-mode' + +(defvar doom-docs-link-alist + '(("doom-tag" . "https://github.com/hlissner/doom-emacs/releases/tag/%s") + ("doom-contrib-core" . "id:9ac0c15c-29e7-43f8-8926-5f0edb1098f0") + ("doom-contrib-docs" . "id:31f5a61d-d505-4ee8-9adb-97678250f4e2") + ("doom-contrib-maintainer" . "id:e71e9595-a297-4c49-bd11-f238329372db") + ("doom-contrib-module" . "id:b461a050-8702-4e63-9995-c2ef3a78f35d") + ("doom-faq" . "id:5fa8967a-532f-4e0c-8ae8-25cd802bf9a9") + ("doom-help" . "id:9bb17259-0b07-45a8-ae7a-fc5e0b16244e") + ("doom-help-changelog" . "id:7c56cc08-b54b-4f4b-b106-a76e2650addd") + ("doom-help-modules" . "id:1ee0b650-f09b-4454-8690-cc145aadef6e") + ("doom-index" . "id:3051d3b6-83e2-4afa-b8fe-1956c62ec096") + ("doom-module-index" . "id:12d2de30-c569-4b8e-bbc7-85dd5ccc4afa") + ("doom-module-issues" . "https://github.com/doomemacs/doomemacs/labels/%s") + ("doom-module-history" . "https://github.com/doomemacs/doomemacs/commits/master/modules/%s") + ("doom-report" . "https://github.com/doomemacs/doomemacs/issues/new/choose") + ("doom-suggest-edit" . "id:31f5a61d-d505-4ee8-9adb-97678250f4e2") + ("doom-suggest-faq" . "id:aa28b732-0512-49ed-a47b-f20586c0f051") + ("github" . "https://github.com/%s"))) + +;;;###autoload +(define-derived-mode doom-docs-org-mode org-mode "Doom Docs" + "A derivative of `org-mode' for Doom's documentation files. + +Keeps track of its own IDs in `doom-docs-dir' and toggles `doom-docs-mode' when +`read-only-mode' is activated." + :after-hook (visual-line-mode -1) + (require 'org-id) + (require 'ob) + (setq-local org-id-link-to-org-use-id t + org-id-method 'uuid + org-id-track-globally t + org-id-locations-file (doom-path doom-cache-dir "doom-docs-org-ids") + org-id-locations doom-docs--id-locations + org-id-files doom-docs--id-files + org-num-max-level 3 + org-footnote-define-inline nil + org-footnote-auto-label t + org-footnote-auto-adjust t + org-footnote-section nil + wgrep-change-readonly-file t + org-link-abbrev-alist-local (append org-link-abbrev-alist-local doom-docs-link-alist) + org-babel-default-header-args + (append '((:eval . "no") (:tangle . "no")) + org-babel-default-header-args) + save-place-ignore-files-regexp ".") + (when (require 'org-glossary nil t) + (setq org-glossary-collection-root doom-docs-dir + org-glossary-global-terms (doom-glob org-glossary-collection-root "appendix.org")) + (require 'ox) + (org-glossary-mode +1)) + (unless org-inhibit-startup + (doom/reload-docs) + (unless (local-variable-p 'org-startup-with-inline-images) + (setq org-display-remote-inline-images 'cache) + (org-display-inline-images)) + (unless (local-variable-p 'org-startup-indented) + (org-indent-mode +1)) + (unless (local-variable-p 'org-startup-numerated) + (when (bound-and-true-p org-num-mode) + (org-num-mode -1)) + (org-num-mode +1)) + (unless (local-variable-p 'org-startup-folded) + (let ((org-startup-folded 'content)) + (org-set-startup-visibility)))) + (add-hook 'read-only-mode-hook #'doom-docs--toggle-read-only-h nil 'local) + (org-with-limited-levels + (end-of-line) + (null (re-search-forward org-outline-regexp-bol nil t)))) + +;;;###autoload +(defun doom-docs-read-only-h () + "Activate `read-only-mode' if the current file exists and is non-empty." + ;; The rationale: if it's empty or non-existant, you want to write an org + ;; file, not read it. + (let ((file-name (buffer-file-name (buffer-base-buffer)))) + (when (and file-name + (> (buffer-size) 0) + (not (string-prefix-p "." (file-name-base file-name))) + (file-exists-p file-name)) + (read-only-mode +1)))) + +(add-hook 'doom-docs-org-mode-hook #'doom-docs-read-only-h) + + +;; +;;; Custom links + +;;;###autoload +(defun doom-docs-read-link-desc-at-point (&optional default context) + "TODO" + (if (and (stringp default) (not (string-empty-p default))) + (string-trim default) + (if-let* ((context (or context (org-element-context))) + (context (org-element-lineage context '(link) t)) + (beg (org-element-property :contents-begin context)) + (end (org-element-property :contents-end context))) + (unless (= beg end) + (replace-regexp-in-string + "[ \n]+" " " (string-trim (buffer-substring-no-properties beg end))))))) + + +;;;###autoload +(defun doom-docs-doom-module-link-follow-fn (link) + (cl-destructuring-bind (&key category module flag) + (doom-docs--read-module-link link) + (when category + (let ((doom-modules-dirs (list doom-modules-dir))) + (if-let* ((path (doom-module-locate-path category module)) + (path (or (car (doom-glob path "README.org")) + path))) + (find-file path) + (user-error "Can't find Doom module '%s'" link)))) + (when flag + (goto-char (point-min)) + (when (and (re-search-forward "^\\*+ \\(?:TODO \\)?Module flags") + (re-search-forward (format "^\\s-*- \\+%s ::[ \n]" + (substring (symbol-name flag) 1)) + (save-excursion (org-get-next-sibling) + (point)))) + (org-show-entry) + (recenter))))) + +;;;###autoload +(defun doom-docs-doom-module-link-face-fn (link) + (cl-destructuring-bind (&key category module flag) + (doom-docs--read-module-link link) + (if (doom-module-locate-path category module) + `(:inherit org-priority + :weight bold) + 'error))) + +;;;###autoload +(defun doom-docs-doom-package-link-follow-fn (link) + "TODO" + (doom/describe-package + (intern-soft + (doom-docs-read-link-desc-at-point link)))) + +;;;###autoload +(defun doom-docs-make-symbol-link (fn) + "TODO" + (lambda (link) + (let ((desc (doom-docs-read-link-desc-at-point link))) + (funcall + fn (or (intern-soft desc) + (user-error "Can't find documentation for %S" desc)))))) + +(defun doom-docs--describe-kbd (keystr) + (dolist (key `(("" . ,doom-leader-key) + ("" . ,doom-localleader-key) + ("" . ,(if (bound-and-true-p evil-mode) + (concat doom-leader-key " u") + "C-u")) + ("" . ,(if (bound-and-true-p evil-mode) + (concat doom-leader-key " h") + "C-h")) + ("\\~ tags in PHP, or ~def end~ in + Ruby/Crystal/etc. + +*** [[doom-module::config literate][literate]]: - +: Disguise your config as poor documentation + +This module enables support for a literate config. + +A literate config consists of a =$DOOMDIR/config.org=. All src blocks within are +tangled =$DOOMDIR/config.el=, by default, when ~$ doom sync~ is executed. + + +** [[doom-module::editor][:editor]] (12) :unfold: +For modules concerned with the insertion and editing of text. Amen. + +*** [[doom-module::editor evil][evil]]: [[doom-module::editor evil +everywhere][+everywhere]] +: The text editor Emacs was missing + +This holy module brings the Vim editing model to Emacs. + +*** [[doom-module::editor file-templates][file-templates]]: - +: Fill the void in your empty files + +This module adds file templates for blank files, powered by [[doom-package:][yasnippet]]. + +*** [[doom-module::editor fold][fold]]: - +: What you can't see won't hurt you + +This module marries [[doom-package:][hideshow]], [[doom-package:][vimish-fold]], and ~outline-minor-mode~ to bring you +marker, indent and syntax-based code folding for as many languages as possible. + +*** [[doom-module::editor format][format]]: [[doom-module::editor format +onsave][+onsave]] +: Standardize your ugly code + +This module integrates code formatters into Emacs. Here are some of the +formatters that it currently supports: + +#+begin_quote +asmfmt, black, brittany, cabal-fmt, clang-format, cmake-format, dartfmt, dfmt, +dhall format, dockfmt, elm-format, emacs, fish_indent, fprettify, gleam format, +gofmt, iStyle, jsonnetfmt, ktlint, latexindent, ledger-mode, lua-fmt, mix +format, nixfmt, node-cljfmt, ocp-indent, perltidy, prettier, purty, rufo, +rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy +#+end_quote + +*** [[doom-module::editor god][god]]: - +: IDDQD + +Adds [[doom-package:][god-mode]] support to Doom Emacs, allowing for entering commands without +modifier keys, similar to Vim's modality, separating command mode and insert +mode. + +*** [[doom-module::editor lispy][lispy]]: - +: Vim for lisp, for people who don't like vim + +This module adds a keybind scheme for navigating and editing S-expressions in +Lisps; including S-exp awareness for Evil users. This affects the following +languages: + +- Common Lisp +- Emacs Lisp +- Scheme +- Racket +- [[http://docs.hylang.org/en/stable/][Hy]] +- [[http://lfe.io/][LFE]] +- Clojure +- [[https://fennel-lang.org][Fennel]] + +*** [[doom-module::editor multiple-cursors][multiple-cursors]]: - +: Make all your mistakes at once + +This module adds a multiple cursors implementation to Emacs (two, if you use +evil) that loosely take after multi-cursors in Atom or Sublime Text. + +*** [[doom-module::editor objed][objed]]: [[doom-module::editor objed +manual][+manual]] +: Text object editing for the innocent + +This modules adds [[doom-package:][objed]], a global minor-mode for navigating and manipulating +text objects. It combines the ideas of ~versor-mode~ and other editors like Vim +or Kakoune and tries to align them with regular Emacs conventions. + +[[https://github.com/clemera/objed][See the objed project README]] for information on keybinds and usage. + +*** [[doom-module::editor parinfer][parinfer]]: - +: For lispers that like Python more (i.e. nobody) + +Parinfer is a minor mode that aids the writing of Lisp code. It automatically +infers parenthesis matching and indentation alignment, keeping your code +balanced and beautiful. + +*** [[doom-module::editor rotate-text][rotate-text]]: - +: The only back'n'forth nerds will ever know + +This module adds text rotation to Doom Emacs. I.e. The ability to cycle through +keywords or text patterns at point, like ~true~ and ~false~, or ~public~, +~protected~, and ~private~ (in ~c++-mode~). + +*** [[doom-module::editor snippets][snippets]]: - +: My elves type so I don't have to + +This module adds snippet expansions to Emacs, powered by [[doom-package:][yasnippet]]. + +*** [[doom-module::editor word-wrap][word-wrap]]: - +: Soft-wrapping with language-aware indent + +This module adds a minor-mode [[fn:][+word-wrap-mode]], which intelligently wraps long +lines in the buffer without modifying the buffer content. + + +** [[doom-module::emacs][:emacs]] (6) :unfold: +Modules in this category augment and extend the built-in features of Emacs. + +*** [[doom-module::emacs dired][dired]]: [[doom-module::emacs dired +icons][+icons]] [[doom-module::emacs dired +ranger][+ranger]] +: Making dired pretty [functional] + +This module provides reasonable defaults and augmentations for dired. + +*** [[doom-module::emacs electric][electric]]: - +: Shocking keyword-based electric-indent + +This module augments the built-in [[doom-package:][electric]] package with keyword-based +indentation (as opposed to character-based). + +*** [[doom-module::emacs ibuffer][ibuffer]]: [[doom-module::emacs ibuffer +icons][+icons]] +: Edit me like one of your French buffers + +This module augments the built-in [[doom-package:][ibuffer]] package. + +- Adds project-based grouping of buffers +- Support for file-type icons +- Uses human-readable file-size + +*** tramp: - +/(No description)/ + +*** [[doom-module::emacs undo][undo]]: [[doom-module::emacs undo +tree][+tree]] +: Persistent, smarter undo for your inevitable mistakes + +This module augments Emacs' built-in undo system to be more intuitive and to +persist across Emacs sessions. + +*** [[doom-module::emacs vc][vc]]: - +: Be the difference you want to see in the fringe + +This module augments Emacs builtin version control support and provides better +integration with =git=. + + +** [[doom-module::email][:email]] (3) :unfold: +Modules that turn Emacs in an email client. + +*** [[doom-module::email mu4e][mu4e]]: [[doom-module::email mu4e +gmail][+gmail]] [[doom-module::email mu4e +org][+org]] +: The great filter Hanson hadn't anticipated + +This module makes Emacs an email client, using [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]]. + +- Tidied mu4e headers view, with flags from [[doom-package:][all-the-icons]]. +- Consistent coloring of reply depths (across compose and gnus modes). +- Prettified =mu4e:main= view. +- Cooperative locking of the =mu= process. Another Emacs instance may request + access, or grab the lock when it's available. +- [[doom-package:][org-msg]] integration with [[doom-module:][+org]], which can be toggled per-message, with revamped + style and an accent color. +- Gmail integrations with the [[doom-module:][+gmail]] flag. +- Email notifications with [[doom-package:][mu4e-alert]], and (on Linux) a customised notification + style. + +#+begin_quote + πŸ’‘ I want to live in Emacs, but as we all know, living is incomplete without + email. So I prayed to the text editor gods and they (I) answered. + Emacs+evil's editing combined with org-mode for writing emails? /Yes + please./ + + It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my + email via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can + understand). +#+end_quote + +*** [[doom-module::email notmuch][notmuch]]: [[doom-module::email notmuch +afew][+afew]] [[doom-module::email notmuch +org][+org]] +: Closest Emacs will ever be to multi-threaded + +This module turns Emacs into an email client using [[doom-package:][notmuch]]. + +*** [[doom-module::email wanderlust][wanderlust]]: [[doom-module::email wanderlust +gmail][+gmail]] +: To boldly go where no mail has gone before + +#+begin_quote + πŸ”¨ This module has no description. [[doom-contrib-module:][Write one?]] +#+end_quote + + +** [[doom-module::input][:input]] (3) :unfold: +Modules in this category extend Emacs support for additional keyboard layouts +and input methods for non-English languages. + +*** [[doom-module::input chinese][chinese]]: - +: Spend your 3 hours a week in Emacs + +This module adds support for traditional Chinese script by introducing two input +methods: Pinyin and Wubi. + +*** [[doom-module::input japanese][japanese]]: - +: Ah, a man of culture + +This module adds support for Japanese script. + +*** [[doom-module::input layout][layout]]: [[doom-module::input layout +azerty][+azerty]] [[doom-module::input layout +bepo][+bepo]] +: auie,ctsrnm is the superior home row + +This module provides barebones support for using Doom with non-qwerty keyboard +layouts. + + +** [[doom-module::lang][:lang]] (60) :unfold: +These modules specialize in integration particular languages and their +ecosystems into (Doom) Emacs. + +*** [[doom-module::lang agda][agda]]: - +: Types of types of types of types... + +This module adds support for the [[http://wiki.portal.chalmers.se/agda/pmwiki.php][agda]] programming language. The Emacs support +exists directly in the agda repository, but not in melpa. + +*** [[doom-module::lang beancount][beancount]]: [[doom-module::lang beancount +lsp][+lsp]] +: Mind the GAAP + +This module adds support for [[https://beancount.github.io/][Beancount]] to Emacs. Beancount, like ledger, lets +you [[https://plaintextaccounting.org/][manage your money in plain text]]. + +*** [[doom-module::lang cc][cc]]: [[doom-module::lang cc +lsp][+lsp]] +: C > C++ == 1 + +This module adds support for the C-family of languages: C, C++, and Objective-C. + +- Code completion (~company-irony~) +- eldoc support (~irony-eldoc~) +- Syntax-checking (~flycheck-irony~) +- Code navigation (~rtags~) +- File Templates ([[../../editor/file-templates/templates/c-mode][c-mode]], [[../../editor/file-templates/templates/c++-mode][c++-mode]]) +- Snippets ([[https://github.com/hlissner/doom-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c++-mode][c++-mode]]) +- Several improvements to C++11 indentation and syntax highlighting. + +*** [[doom-module::lang clojure][clojure]]: [[doom-module::lang clojure +lsp][+lsp]] +: Java with a lisp + +This module adds support for the Clojure(Script) language. + +- Interactive development environment (~cider~): REPL, compilation, debugging, + running tests, definitions & documentation lookup, code completion, and much + more +- Refactoring (~clj-refactor~) +- Linting (~clj-kondo~), requires ~:checkers syntax~ +- LSP support (~clojure-lsp~) + +*** [[doom-module::lang common-lisp][common-lisp]]: - +: If you've seen one lisp, you've seen them all + +This module provides support for [[https://lisp-lang.org/][Common Lisp]] and the [[doom-package:][Sly]] development +environment. Common Lisp is not a single language but a specification, with many +competing compiler implementations. By default, [[http://www.sbcl.org/][Steel Bank Common Lisp]] (SBCL) is +assumed to be installed, but this can be configured. + +Common Lisp benefits from a mature specification and rich standard library. +Thanks to its powerful REPL and debugger, it boasts an "interactive programming" +style often unseen in other languages. Compiled Common Lisp programs are trusted +to run unmodified for a long time. + +*** [[doom-module::lang coq][coq]]: - +: Proofs as programs + +This module adds [[https://coq.inria.fr][coq]] support, powered by [[https://proofgeneral.github.io][Proof General]]. + +- Code completion ([[https://github.com/cpitclaudel/company-coq][company-coq]]) +- [[https://github.com/hlissner/doom-snippets/tree/master/coq-mode][Snippets]] + +*** [[doom-module::lang crystal][crystal]]: - +: Ruby at the speed of C + +This modules adds [[https://crystal-lang.org/][crystal]] support. + +- Syntax-checking (~flycheck~) +- REPL (~inf-crystal~) + +*** [[doom-module::lang csharp][csharp]]: [[doom-module::lang csharp +dotnet][+dotnet]] [[doom-module::lang csharp +lsp][+lsp]] [[doom-module::lang csharp +unity][+unity]] +: Unity, .NET, and Mono shenanigans + +This module adds C# support to Emacs, powered by Omnisharp (directly or through +LSP). + +*** [[doom-module::lang dart][dart]]: [[doom-module::lang dart +flutter][+flutter]] [[doom-module::lang dart +lsp][+lsp]] +: Paint ui and not much else + +[[https://dart.dev/][Dart]] is a client-optimized language by Google for fast apps on any platform. It +is fast and optimized for UI, famous for the [[https://flutter.io/][Flutter]] framework, also made by +Google. Both Flutter and Dart are free and open-source. + +This module wraps ~dart-mode~, with [[https://microsoft.github.io/language-server-protocol/][LSP]] features like code completion for +=.dart= files, syntax highlighting, debugging, closing labels, etc. + +*** [[doom-module::lang data][data]]: - +: A dumping ground for data formats + +This module adds Emacs support for CSV and XML files. + +*** [[doom-module::lang dhall][dhall]]: - +: Config as code + +This module adds [[https://dhall-lang.org/][Dhall]] language support to Emacs. + +Dhall is a programmable configuration language that you can think of as: JSON + +functions + types + imports. + +*** [[doom-module::lang elixir][elixir]]: [[doom-module::lang elixir +lsp][+lsp]] +: Erlang done right + +This module provides support for [[https://elixir-lang.org/][Elixir programming language]] via [[doom-package:][alchemist]] or +[[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]]. + +*** [[doom-module::lang elm][elm]]: [[doom-module::lang elm +lsp][+lsp]] +: Care for a cup of TEA? + +This module adds [[https://elm-lang.org/][Elm]] support to Doom Emacs. + +*** [[doom-module::lang emacs-lisp][emacs-lisp]]: - +: A parsel-tongue for the oldest serpent + +This module extends support for Emacs Lisp in Doom Emacs. + +- Macro expansion +- Go-to-definitions or references functionality +- Syntax highlighting for defined and quoted symbols +- Replaces the built-in help with the more powerful [[doom-package:][helpful]] +- Adds function example uses to documentation + +*** [[doom-module::lang erlang][erlang]]: [[doom-module::lang erlang +lsp][+lsp]] +: An elegant language for a more civilized age + +This module provides support [[https://www.erlang.org/][Erlang programming language]]. Support for the +[[https://github.com/erlang/sourcer][sourcer]] language server is optional. + +Includes: +- Code completion ([[doom-module:][+lsp]], [[doom-module:][:completion company]], & [[doom-module:][:completion ivy]]) +- Syntax checking ([[doom-module:][:checkers syntax]]) + +*** [[doom-module::lang ess][ess]]: [[doom-module::lang ess +stan][+stan]] +: 73.6% of all statistics are made up + +This module adds support for various statistics languages, including R, S-Plus, +SAS, Julia and Stata. + +*** [[doom-module::lang factor][factor]]: - +: ... + +This module adds support to the [[https://github.com/factor/factor][factor]] programming language and its associated +[[doom-package:][fuel]] emacs plugin. + +*** [[doom-module::lang faust][faust]]: - +: DSP, but you can keep your soul + +Add support to [[https://faust.grame.fr/][Faust language]] inside emacs. + +- Faust code syntax highlighting and indentation +- Project-based (inter-linked Faust files) +- Build/compile with output window +- Graphic diagrams generation and visualization in the (default) browser +- Browse generated C++ code inside Emacs +- Inter-linked files/buffers : + - From "component" to Faust file + - From "include" to Faust library file +- From error to file:line number +- From function name to online documentation +- Fully configurable (build type/target/architecture/toolkit, keyboard + shortcuts, etc.) +- Automatic keyword completion (if Auto-Complete is installed) +- Automatic objets (functions, operators, etc.) template insertion with default + sensible values (if [[doom-module:][:editor snippets]] is enabled) +- Modeline indicator of the state of the code + +*** [[doom-module::lang fsharp][fsharp]]: [[doom-module::lang fsharp +lsp][+lsp]] +: ML stands for Microsoft's Language + +This module adds [[https://fsharp.org/][F#]] support to Doom Emacs. + +*** [[doom-module::lang fstar][fstar]]: - +: (Dependent) types and (monadic) effects and Z3 + +This module adds [[https://fstar-lang.org/][F*]] support, powered by [[https://github.com/FStarLang/fstar-mode.el][fstar-mode.el]]. + +- Syntax highlighting +- Interactively process F* files one definition at a time +- Query the running F* process to look up definitions, documentation, and + theorems + +*** [[doom-module::lang gdscript][gdscript]]: [[doom-module::lang gdscript +lsp][+lsp]] +: the language you waited for + +This module adds support for GDScript, the scripting language of the [[http://godotengine.org/][Godot]] game +engine, to Doom Emacs, powered by [[https://github.com/GDQuest/emacs-gdscript-mode][gdscript-mode]]. + +*** [[doom-module::lang go][go]]: [[doom-module::lang go +lsp][+lsp]] +: The hipster dialect + +This module adds [[https://golang.org][Go]] support, with optional (but recommended) LSP support via +[[https://github.com/golang/tools/blob/master/gopls/README.md][gopls]]. + +- Code completion (~gocode~) +- Documentation lookup (~godoc~) +- Eldoc support (~go-eldoc~) +- REPL (~gore~) +- Syntax-checking (~flycheck~) +- Auto-formatting on save (~gofmt~) (requires [[doom-module:][:editor format +onsave]]) +- Code navigation & refactoring (~go-guru~) +- [[../../editor/file-templates/templates/go-mode][File templates]] +- [[https://github.com/hlissner/doom-snippets/tree/master/go-mode][Snippets]] +- Generate testing code (~go-gen-test~) +- Code checking (~flycheck-golangci-lint~) + +*** [[doom-module::lang haskell][haskell]]: [[doom-module::lang haskell +lsp][+lsp]] +: A language that's lazier than I am + +This module adds Haskell support to Doom Emacs. + +*** [[doom-module::lang hy][hy]]: - +: Lisp is better than ugly + +/(No description yet)/ + +*** [[doom-module::lang idris][idris]]: - +: A language you can depend on + +This module adds rudimentary [[https://www.idris-lang.org/][Idris]] support to Doom Emacs. + +*** [[doom-module::lang java][java]]: [[doom-module::lang java +lsp][+lsp]] [[doom-module::lang java +meghanada][+meghanada]] +: The poster child for carpal tunnel syndrome + +This module adds [[https://www.java.com][Java]] support to Doom Emacs, including ~android-mode~ and +~groovy-mode~. + +*** [[doom-module::lang javascript][javascript]]: [[doom-module::lang javascript +lsp][+lsp]] +: all(hope(abandon(ye(who(enter(here)))))) + +This module adds [[https://www.javascript.com/][JavaScript]] and [[https://www.typescriptlang.org/][TypeScript]] support to Doom Emacs. + +- Code completion ([[doom-package:][tide]]) +- REPL support ([[doom-package:][nodejs-repl]]) +- Refactoring commands ([[doom-package:][js2-refactor]]) +- Syntax checking ([[doom-package:][flycheck]]) +- Browser code injection with [[doom-package:][skewer-mode]] +- Coffeescript & JSX support +- Jump-to-definitions and references support ([[doom-package:][xref]]) + +*** [[doom-module::lang json][json]]: [[doom-module::lang json +lsp][+lsp]] +: At least it ain't XML + +This module adds [[https://www.json.org/json-en.html][JSON]] support to Doom Emacs. + +*** [[doom-module::lang julia][julia]]: [[doom-module::lang julia +lsp][+lsp]] +: A better, faster MATLAB + +This module adds support for [[https://julialang.org/][the Julia language]] to Doom Emacs. + +- Syntax highlighting and latex symbols from [[doom-package:][julia-mode]] +- REPL integration from [[doom-package:][julia-repl]] +- Code completion and syntax checking, requires [[doom-module:][:tools lsp]] and [[doom-module:][+lsp]] + +*** [[doom-module::lang kotlin][kotlin]]: [[doom-module::lang kotlin +lsp][+lsp]] +: A Java(Script) that won't depress you + +This module adds [[https://kotlinlang.org/][Kotlin]] support to Doom Emacs. + +*** [[doom-module::lang latex][latex]]: [[doom-module::lang latex +cdlatex][+cdlatex]] [[doom-module::lang latex +fold][+fold]] [[doom-module::lang latex +latexmk][+latexmk]] [[doom-module::lang latex +lsp][+lsp]] +: Writing papers in Emacs has never been so fun + +Provide a helping hand when working with LaTeX documents. + +- Sane defaults +- Fontification of many popular commands +- Pretty indentation of wrapped lines using the [[doom-package:][adaptive-wrap]] package +- Spell checking with [[doom-package:][flycheck]] +- Change PDF viewer to Okular or [[doom-package:][latex-preview-pane]] +- Bibtex editor +- Autocompletion using [[doom-package:][company-mode]] +- Compile your =.tex= code only once using LatexMk + +*** [[doom-module::lang lean][lean]]: - +: For folks with too much to prove + +This module adds support for the [[https://leanprover.github.io/about/][Lean programming language]] to Doom Emacs. + +*** [[doom-module::lang ledger][ledger]]: - +: Be audit you can be + +This module adds support for [[https://www.ledger-cli.org/][ledger]] files. Ledger is a command line double-entry +accounting system that works with simple text files holding transactions in the +following format: +#+begin_src ledger +2015/10/12 Exxon + Expenses:Auto:Gas $10.00 + Liabilities:MasterCard $-10.00 +#+end_src + +This modules enables the following features: +- Syntax and indentation support for ledger files +- Add, edit, and delete transactions +- Generate reports +- Schedule transactions +- Sort transactions +- Display statistics about transactions +- Display balance up to a point + +*** [[doom-module::lang lua][lua]]: [[doom-module::lang lua +fennel][+fennel]] [[doom-module::lang lua +lsp][+lsp]] [[doom-module::lang lua +moonscript][+moonscript]] +: One-based indices? one-based indices + +This module adds Lua support to Doom Emacs. + +- REPL +- Love2D specific functions +- Moonscript support +- Fennel support + +*** [[doom-module::lang markdown][markdown]]: [[doom-module::lang markdown +grip][+grip]] +: Write docs for people to ignore + +This module provides Markdown support for Emacs. + +#+begin_quote +Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you +to write using an easy-to-read, easy-to-write plain text format, then convert it +to structurally valid XHTML (or HTML). + +Thus, β€œMarkdown” is two things: (1) a plain text formatting syntax; and (2) a +software tool, written in Perl, that converts the plain text formatting to HTML. +See the Syntax page for details pertaining to Markdown's formatting syntax. You +can try it out, right now, using the online Dingus. + +The overriding design goal for Markdown's formatting syntax is to make it as +readable as possible. The idea is that a Markdown-formatted document should be +publishable as-is, as plain text, without looking like it's been marked up with +tags or formatting instructions. While Markdown's syntax has been influenced by +several existing text-to-HTML filters, the single biggest source of inspiration +for Markdown's syntax is the format of plain text email. -- John Gruber +#+end_quote + +*** [[doom-module::lang nim][nim]]: - +: Python + lisp at the speed of C + +This module adds [[https://nim-lang.org][Nim]] support to Doom Emacs. + +- Code completion ([[doom-package:][nimsuggest]] + [[doom-package:][company]]) +- Syntax checking ([[doom-package:][nimsuggest]] + [[doom-package:][flycheck]]) +- Org babel support ([[doom-package:][ob-nim]]) + +*** [[doom-module::lang nix][nix]]: - +: I hereby declare "nix geht mehr!" + +This module adds support for the Nix language to Doom Emacs, along with tools +for managing [[https://nixos.org/][Nix(OS)]]. + +Includes: +- Syntax highlighting +- Completion through [[doom-package:][company]] and/or [[doom-package:][helm]] +- Nix option lookup +- Formatting (~nixfmt~) + +*** [[doom-module::lang ocaml][ocaml]]: [[doom-module::lang ocaml +lsp][+lsp]] +: An objective camel + +This module adds [[https://ocaml.org/][OCaml]] support to Doom Emacs, powered by [[doom-package:][tuareg-mode]]. + +- Code completion, documentation look-up, code navigation and refactoring + ([[doom-package:][merlin]]) +- Type, documentation and function argument display on idle ([[doom-package:][merlin-eldoc]]) +- REPL ([[doom-package:][utop]]) +- Syntax-checking ([[doom-package:][merlin]] with [[doom-package:][flycheck-ocaml]]) +- Auto-indentation ([[doom-package:][ocp-indent]]) +- Code formatting ([[doom-package:][ocamlformat]]) +- Dune file format ([[doom-package:][dune]]) + +*** [[doom-module::lang org][org]]: [[doom-module::lang org +brain][+brain]] [[doom-module::lang org +dragndrop][+dragndrop]] [[doom-module::lang org +gnuplot][+gnuplot]] [[doom-module::lang org +hugo][+hugo]] [[doom-module::lang org +ipython][+ipython]] [[doom-module::lang org +journal][+journal]] [[doom-module::lang org +jupyter][+jupyter]] [[doom-module::lang org +noter][+noter]] [[doom-module::lang org +pandoc][+pandoc]] [[doom-module::lang org +pomodoro][+pomodoro]] [[doom-module::lang org +present][+present]] [[doom-module::lang org +pretty][+pretty]] [[doom-module::lang org +roam][+roam]] [[doom-module::lang org +roam2][+roam2]] +: Organize your plain life in plain text + +This module adds org-mode support to Doom Emacs, along with a number of +adjustments, extensions and reasonable defaults to make it more performant and +intuitive out of the box: + +- A custom, centralized attachment system that stores files in one place, rather + than in the same directory as the input file(s) (only applies to attachments + from files in/under ~org-directory~). +- Executable code blocks with support for a variety of languages and tools + (depending on what :lang modules are enabled). +- Supports an external org-capture workflow through the =bin/org-capture= shell + script and ~+org-capture/open-frame~. +- A configuration for using org-mode for slide-show presentations or exporting + org files to reveal.js slideshows. +- Drag-and-drop support for images (with inline preview) and media files (drops + a file icon and a short link) (requires [[doom-module:][+dragndrop]] flag). +- Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others + (requires flags). +- Export-to-clipboard functionality, for copying text into formatted html, + markdown or rich text to the clipboard (see ~+org/export-to-clipboard~ and + ~+org/export-to-clipboard-as-rich-text~). + +#+begin_quote +Org is a system for writing plain text notes with syntax highlighting, code +execution, task scheduling, agenda management, and many more. The whole idea is +that you can write notes and mix them with references to things like articles, +images, and example code combined with the output of that code after it is +executed. + +https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/ +#+end_quote + +*** [[doom-module::lang php][php]]: [[doom-module::lang php +hack][+hack]] [[doom-module::lang php +lsp][+lsp]] +: Perl's insecure younger brother + +This module adds support for PHP 5.3+ (including PHP7) to Doom Emacs. + +- ctags-based code completion (~company-php~ and ~phpctags~) +- eldoc support (~ac-php~ and ~php-extras~) +- REPL (~php-boris~) +- Code refactoring commands (~php-refactor-mode~) +- Unit-test commands (~phpunit~) +- Support for ~laravel~ and ~composer~ projects (with project-specific snippets) +- [[../../editor/file-templates/templates/php-mode][File templates]] +- [[https://github.com/hlissner/doom-snippets/tree/master/php-mode][Snippets]] + +#+begin_quote + πŸ’‘ PHP was the first programming language I got paid to code in, back in the + Cretaceous period (2003). My sincerest apologies go out to all the + programmers who inherited my earliest PHP work. I know you're out there, + writhing in your straitjackets. + + Save a programmer today. Stop a friend from choosing PHP as their first + language. +#+end_quote + +*** [[doom-module::lang plantuml][plantuml]]: - +: Diagrams to confuse people more + +This module adds plantuml support to Emacs; allowing you to generate diagrams +from plain text. + +*** [[doom-module::lang purescript][purescript]]: [[doom-module::lang purescript +lsp][+lsp]] +: Javascript, but functional + +This module adds [[https://www.purescript.org/][Purescript]] support to Doom Emacs. + +*** [[doom-module::lang python][python]]: [[doom-module::lang python +conda][+conda]] [[doom-module::lang python +cython][+cython]] [[doom-module::lang python +lsp][+lsp]] [[doom-module::lang python +poetry][+poetry]] [[doom-module::lang python +pyenv][+pyenv]] [[doom-module::lang python +pyright][+pyright]] +: Beautiful is better than ugly + +This module adds [[https://www.python.org/][Python]] support to Doom Emacs. + +- Syntax checking ([[doom-package:][flycheck]]) +- Snippets +- Run tests ([[doom-package:][nose]], [[doom-package:][pytest]]) +- Auto-format (with ~black~, requires [[doom-module:][:editor format]]) +- LSP integration (=mspyls=, =pyls=, or =pyright=) + +*** [[doom-module::lang qt][qt]]: - +: The cutest GUI framework ever + +This module provides language functionality for [[https://qt.io][Qt]] specific files. + +- Syntax highlighting for [[https:://en.wikipedia.org/wiki/QML][qml]] files +- Syntax highlighting for =.pro= and =.pri= files used by [[https://doc.qt.io/qt-5/qmake-project-files.html][qmake]] + +*** [[doom-module::lang racket][racket]]: [[doom-module::lang racket +lsp][+lsp]] [[doom-module::lang racket +xp][+xp]] +: The DSL for DSLs + +This module adds support for the [[https://www.racket-lang.org/][Racket programming language]] to Doom Emacs. + +*** [[doom-module::lang raku][raku]]: - +: The artist formerly known as perl6 + +This module adds support for the [[https://www.raku.org/][Raku programming language]] to Doom Emacs. + +*** [[doom-module::lang rest][rest]]: - +: Emacs as a REST client + +This module turns Emacs into a [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] client. + +- Code-completion (~company-restclient~) +- Code evaluation +- Imenu support for ~restclient-mode~ +- org-mode: babel support (~ob-restclient~) + +#+begin_quote + πŸ’‘ ~restclient-mode~ is tremendously useful for automated or quick testing REST + APIs. My workflow is to open an ~org-mode~ buffer, create a restclient + source block and hack away. ~restclient-mode~ and ~company-restclient~ power + this arcane wizardry. +#+end_quote + +*** [[doom-module::lang rst][rst]]: - +: ReST in peace + +This module adds [[https://docutils.sourceforge.io/rst.html][ReStructured Text]] support to Doom Emacs. + +*** [[doom-module::lang ruby][ruby]]: [[doom-module::lang ruby +chruby][+chruby]] [[doom-module::lang ruby +lsp][+lsp]] [[doom-module::lang ruby +rails][+rails]] [[doom-module::lang ruby +rbenv][+rbenv]] [[doom-module::lang ruby +rvm][+rvm]] +: 1.step {|i| p "Ruby is #{i.even? ? 'love' : 'life'}"} + +This module add Ruby and optional Ruby on Rails support to Emacs. + +- Code completion ([[doom-package:][robe]]) +- Syntax checking ([[doom-package:][flycheck]]) +- Jump-to-definitions ([[doom-package:][robe]]) +- Bundler +- Rubocop integration ([[doom-package:][flycheck]]) + +*** [[doom-module::lang rust][rust]]: [[doom-module::lang rust +lsp][+lsp]] +: Fe2O3.unwrap().unwrap().unwrap().unwrap() + +This module adds support for the Rust language and integration for its tools, +e.g. ~cargo~. + +- Code completion ([[doom-package:][racer]] or an LSP server) +- Syntax checking ([[doom-package:][flycheck]]) +- LSP support (for rust-analyzer and rls) ([[doom-package:][rustic]]) +- Snippets + +*** [[doom-module::lang scala][scala]]: [[doom-module::lang scala +lsp][+lsp]] +: Java, but good + +This module adds [[https://www.scala-lang.org][scala]] and [[https://www.scala-sbt.org/][sbt]] support to Doom Emacs. + +Through the power of [[https://scalameta.org/metals/docs/editors/overview.html][Metals]] (LSP) this module offers: +- Goto Definition +- Completions +- Hover +- Paremeter Hints +- Find References +- Run/Debug +- Find Implementations +- Rename Symbol +- Code Actions +- Document Symbols +- Formatting +- Folding +- Organize Imports + +*** [[doom-module::lang scheme][scheme]]: [[doom-module::lang scheme +chez][+chez]] [[doom-module::lang scheme +chibi][+chibi]] [[doom-module::lang scheme +chicken][+chicken]] [[doom-module::lang scheme +gambit][+gambit]] [[doom-module::lang scheme +gauche][+gauche]] [[doom-module::lang scheme +guile][+guile]] [[doom-module::lang scheme +kawa][+kawa]] [[doom-module::lang scheme +mit][+mit]] [[doom-module::lang scheme +racket][+racket]] +: A fully conniving family of lisps + +This module provides support for the Scheme family of Lisp languages, powered by +[[https://www.nongnu.org/geiser/geiser_1.html#introduction][geiser]]. + +*** [[doom-module::lang sh][sh]]: [[doom-module::lang sh +fish][+fish]] [[doom-module::lang sh +lsp][+lsp]] [[doom-module::lang sh +powershell][+powershell]] +: She sells {ba,z,fi}sh shells on the C xor + +This module adds support for shell scripting languages (including Powershell and +Fish script) to Doom Emacs. + +- Code completion ([[doom-package:][company-shell]]) +- Syntax Checking ([[doom-package:][flycheck]]) + +*** [[doom-module::lang sml][sml]]: - +: ... + +THis module adds [[https://smlfamily.github.io/][SML (Standard ML) programming language]] support to Doom Emacs. + +*** [[doom-module::lang solidity][solidity]]: - +: Do you need a blockchain? No. + +This module adds [[https://github.com/ethereum/solidity][Solidity]] support to Doom Emacs. + +- Syntax-checking ([[doom-package:][flycheck]]) +- Code completion ([[doom-package:][company-solidity]]) +- Gas estimation (~C-c C-g~) + +*** [[doom-module::lang swift][swift]]: [[doom-module::lang swift +lsp][+lsp]] +: We asked for emoji variables? + +This module adds support for the [[https://developer.apple.com/swift/][Swift programming language]] to Doom Emacs. + +*** [[doom-module::lang terra][terra]]: - +: Earth and Moon in alignment for performance. + +/(No description)/ + +*** [[doom-module::lang web][web]]: [[doom-module::lang web +lsp][+lsp]] +: The tubes + +This module adds support for various web languages, including HTML5, CSS, +SASS/SCSS, Pug/Jade/Slim, and HAML, as well as various web frameworks, like +ReactJS, Wordpress, Jekyll, Phaser, AngularJS, Djano, and more. + +*** [[doom-module::lang yaml][yaml]]: [[doom-module::lang yaml +lsp][+lsp]] +: JSON, but readable + +This module provides support for the [[https://yaml.org/][YAML file format]] to Doom Emacs. + +*** [[doom-module::lang zig][zig]]: [[doom-module::lang zig +lsp][+lsp]] +: C, but simpler + +This module adds [[https://ziglang.org/][Zig]] support, with optional (but recommended) LSP support via +[[https://github.com/zigtools/zls][zls]]. + +- Syntax highlighting +- Syntax-checking ([[doom-package:][flycheck]]) +- Code completion and LSP integration (~zls~) + + +** [[doom-module::os][:os]] (2) :unfold: +Modules in this category are designed to improve compatibility with certain +operating systems or OS features (like the shell). + +*** [[doom-module::os macos][macos]]: - +: Compatibility for our favorite walled garden + +This module provides extra functionality for macOS. + +*** [[doom-module::os tty][tty]]: [[doom-module::os tty +osc][+osc]] +: Make TTY Emacs suck less + +This module configures Emacs for use in the terminal, by providing: + +- System clipboard integration (through an external clipboard program or OSC-52 + escape codes in supported terminals). +- Cursor-shape changing across evil states (requires a terminal that supports + it). +- Mouse support in the terminal. + + +** [[doom-module::term][:term]] (4) :unfold: +What's an operating system without a terminal? The modules in this category +bring varying degrees of terminal emulation into Emacs. + +If you can't decide which to choose, I recommend [[doom-package:][vterm]] or [[doom-package:][eshell]]. [[doom-module:][:term vterm]] +offers that best terminal emulation available but requires a few extra steps to +get going. [[doom-module:][:term eshell]] works everywhere that Emacs runs, even Windows, and +provides a shell entirely implemented in Emacs Lisp. + +*** [[doom-module::term eshell][eshell]]: - +: The elisp shell that works everywhere + +This module provides additional features for the built-in [[https://www.gnu.org/software/emacs/manual/html_mono/eshell.html][Emacs Shell]] + +The Emacs Shell or [[doom-package:][eshell]] is a shell-like command interpreter implemented in +Emacs Lisp. It is an alternative to traditional shells such as =bash=, =zsh=, +=fish=, etc. that is built into Emacs and entirely cross-platform. + +*** [[doom-module::term shell][shell]]: - +: A REPL for your shell + +Provides a REPL for your shell. + +#+begin_quote + πŸ’‘ =shell= is more REPL than terminal emulator. You can edit your command line + like you would any ordinary text in Emacs -- something you can't do in [[doom-package:][term]] + (without ~term-line-mode~, which can be unstable) or [[doom-package:][vterm]]. + + Due to =shell='s simplicity, you're less likely to encounter edge cases + (e.g. against your shell config), but it's also the least capable. TUI + programs like =htop= or =vim= won't work in shell directly, but will be + launched in a =term= buffer -- which handles them reasonably well. +#+end_quote + +*** [[doom-module::term term][term]]: - +: It's terminal + +/(No description)/ + +*** [[doom-module::term vterm][vterm]]: - +: As good as terminal emulation gets in Emacs + +This module provides a terminal emulator powered by libvterm. It is still in +alpha and requires a component be compiled (=vterm-module.so=). + +#+begin_quote + πŸ’‘ [[doom-package:][vterm]] is as good as terminal emulation gets in Emacs (at the time of + writing) and the most performant, as it is implemented in C. However, it + requires extra steps to set up: + + - Emacs must be built with dynamic modules support, + - and =vterm-module.so= must be compiled, which depends on =libvterm=, + =cmake=, and =libtool-bin=. + + [[doom-package:][vterm]] will try to automatically build =vterm-module.so= when you first open + it, but this will fail on Windows, NixOS and Guix out of the box. Install + instructions for nix/guix can be found in the [[doom-module:][:term vterm]] module's + documentation. There is no way to install vterm on Windows that I'm aware of + (but perhaps with WSL?). +#+end_quote + + +** [[doom-module::tools][:tools]] (21) :unfold: +Modules that integrate external tools into Emacs. + +*** [[doom-module::tools ansible][ansible]]: - +: Allow silly people to focus on silly things + +/(No description)/ + +*** biblio: - +/(No description)/ + +*** [[doom-module::tools debugger][debugger]]: [[doom-module::tools debugger +lsp][+lsp]] +: Step through code to help you add bugs + +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. + +*** [[doom-module::tools direnv][direnv]]: - +: Save (or destroy) the environment at your leisure + +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. + + 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 + +*** [[doom-module::tools docker][docker]]: [[doom-module::tools docker +lsp][+lsp]] +: Yo dawg, I heard you like OSes, so I… + +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. + +[[doom-package:][docker-tramp]] offers [[https://www.gnu.org/software/tramp/][TRAMP]] support for Docker containers. + +*** [[doom-module::tools editorconfig][editorconfig]]: - +: Let someone else argue tabs and spaces + +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]]). + +*** [[doom-module::tools ein][ein]]: - +: Tame Jupyter notebooks with emacs + +Adds [[https://jupyter.org/][Jupyter]] notebook integration into Emacs. + +*** [[doom-module::tools eval][eval]]: [[doom-module::tools eval +overlay][+overlay]] +: Run code, run (also, repls) + +This modules adds inline code evaluation support to Emacs and a universal +interface for opening and interacting with REPLs. + +*** [[doom-module::tools gist][gist]]: - +: A pastebin for Githubsters + +Adds the ability to manage, pull from, or push to your [[https://gist.github.com][Gists]] from within Emacs. + +*** [[doom-module::tools lookup][lookup]]: [[doom-module::tools lookup +dictionary][+dictionary]] [[doom-module::tools lookup +docsets][+docsets]] [[doom-module::tools lookup +offline][+offline]] +: Navigate your labyrinthine code and docs + +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 [[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. + +*** [[doom-module::tools lsp][lsp]]: [[doom-module::tools lsp +eglot][+eglot]] [[doom-module::tools lsp +peek][+peek]] +: M-x vscode + +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 +[[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 | +|------------------+---------------------------------------------------------+---------------------------------------------------------------| +| [[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 | + +*** [[doom-module::tools magit][magit]]: [[doom-module::tools magit +forge][+forge]] +: Wield git like a wizard + +This module provides Magit, an interface to the Git version control system. + +*** [[doom-module::tools make][make]]: - +: The discount build system + +This module adds commands for executing Makefile targets. + +*** [[doom-module::tools pass][pass]]: [[doom-module::tools pass +auth][+auth]] +: A password manager for nerds + +This module provides an Emacs interface to [[https://www.passwordstore.org/][Pass]]. + +*** [[doom-module::tools pdf][pdf]]: - +: Emacs, your next PDF reader + +This module improves support for reading and interacting with PDF files in +Emacs. + +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 [[doom-package:][pdf-tools]]. See [[https://github.com/politza/pdf-tools][its project website]] +for details and videos. + +*** [[doom-module::tools prodigy][prodigy]]: - +: No sweatshop is complete without child processes + +This module provides an interface for managing external services from within +Emacs. + +*** [[doom-module::tools rgb][rgb]]: - +: Creating color strings + +Highlights color hex values and names with the color itself, and provides tools +to easily modify color values or formats. + +*** [[doom-module::tools taskrunner][taskrunner]]: - +: Taskrunner for all your projects + +This module integrates [[doom-package:][taskrunner]] into Doom Emacs, which scraps runnable tasks +from build systems like make, gradle, npm and the like. + +*** [[doom-module::tools terraform][terraform]]: - +: Infrastructure as code + +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. + +*** [[doom-module::tools tmux][tmux]]: - +: From one multiplexer to another + +This module provides an API for talking to Tmux sessions. + +*** [[doom-module::tools upload][upload]]: - +: Map local directories to remotes via ssh/ftp + +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 +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 + + +** [[doom-module::ui][:ui]] (23) :unfold: +For modules concerned with changing Emacs' appearance or providing interfaces +for its features, like sidebars, tabs, or fonts. + +*** [[doom-module::ui deft][deft]]: - +: Notational velocity for Emacs + +[[https://jblevins.org/projects/deft/][Deft]] is a major mode for creating, browsing, and filtering notes written in +plain text formats, such as org-mode, markdown, and LaTeX. It enables you to +quickly jot down thoughts and easily retrieve them later. + +*** [[doom-module::ui doom][doom]]: - +: Make Doom fabulous again + +This module gives Doom its signature look: powered by the [[doom-package:doom-themes][doom-one]] theme +(loosely inspired by [[https://github.com/atom/one-dark-syntax][Atom's One Dark theme]]) and [[doom-package:][solaire-mode]]. Includes: + +- A custom folded-region indicator for [[doom-package:][hideshow]]. +- "Thin bar" fringe bitmaps for [[doom-package:][git-gutter-fringe]]. +- File-visiting buffers are slightly brighter (thanks to [[doom-package:][solaire-mode]]). + +*** [[doom-module::ui doom-dashboard][doom-dashboard]]: - +: Welcome to your doom + +This module adds a minimalistic, Atom-inspired dashboard to Emacs. + +Besides eye candy, the dashboard serves two other purposes: + +1. To improve Doom's startup times (the dashboard is lighter than the scratch + buffer in many cases). + +2. And to preserve the "last open directory" you were in. Occasionally, I kill + the last buffer in my project and I end up who-knows-where (in the working + directory of another buffer/project). It can take some work to find my way + back to where I was. Not with the Dashboard. + + Since the dashboard cannot be killed, and it remembers the working directory + of the last open buffer, ~M-x find-file~ will work from the directory I + expect. + +*** [[doom-module::ui doom-quit][doom-quit]]: - +: One does not simply quit Emacs + +A silly module that throws cute confirmation prompts at you when you exit Emacs, +like DOOM (the game) did. Some quotes are from the classic games, others are +random, nerdy references that no decent human being has any business +recognizing. + +*** [[doom-module::ui emoji][emoji]]: [[doom-module::ui emoji +ascii][+ascii]] [[doom-module::ui emoji +github][+github]] [[doom-module::ui emoji +unicode][+unicode]] +: πŸ’© + +This module gives Emacs the ability to display and insert emojis (ASCII, Github +style, or unicode styles), as well as convert certain text patterns (e.g. +=:smile:=) into emojis. + +*** [[doom-module::ui hl-todo][hl-todo]]: - +: TODO FIXME NOTE DEPRECATED HACK REVIEW + +This module adds syntax highlighting for various tags in code comments, such as +=TODO=, =FIXME=, and =NOTE=, among others. + +*** [[doom-module::ui hydra][hydra]]: - +: Discount modality for mythological beast hunters + +This module adds hydra to Doom Emacs, as well as a few custom built hydras to +start with: + +- A hydra to control windows ~+hydra/window-nav/body~. +- A hydra to control text zoom level ~+hydra/text-zoom/body~. + +*** [[doom-module::ui indent-guides][indent-guides]]: - +: Line up them indent columns + +/(No description)/ + +*** [[doom-module::ui ligatures][ligatures]]: [[doom-module::ui ligatures +extra][+extra]] [[doom-module::ui ligatures +fira][+fira]] [[doom-module::ui ligatures +hasklig][+hasklig]] [[doom-module::ui ligatures +iosevka][+iosevka]] [[doom-module::ui ligatures +pragmata-pro][+pragmata-pro]] +: Distract folks from your code + +This module enables ligatures and arbitrary symbol substitutions with +~mac-auto-operator-composition-mode~ (on supported macOS systems) or composition +tables (harfbuzz on Emacs 28), falling back on ~prettify-symbols-mode~ +otherwise. + +*** [[doom-module::ui minimap][minimap]]: - +: A map for lost programmers + +This module displays a minimap of the buffer in a sidebar, similar to the +feature found in many other editors. + +*** [[doom-module::ui modeline][modeline]]: [[doom-module::ui modeline +light][+light]] +: Snazzy, Atom-inspired modeline, plus API + +This module provides an Atom-inspired, minimalistic modeline for Doom Emacs, +powered by the [[doom-package:][doom-modeline]] package (where you can find screenshots). + +*** [[doom-module::ui nav-flash][nav-flash]]: - +: Blink after big motions + +This module flashes the line around the cursor after any significant motion, to +make it easy to follow after big operations. + +#+begin_quote + πŸ’‘ Tremendously helpful on large, 1600p+ or 4K displays. +#+end_quote + +*** [[doom-module::ui neotree][neotree]]: - +: NERDTree for evil nerds + +This module brings a side panel for browsing project files, inspired by vim's +NERDTree. + +#+begin_quote + πŸ’‘ Sure, there's [[doom-package:][dired]] and [[doom-package:][projectile]], but sometimes I'd like a bird's eye view + of a project. +#+end_quote + +*** [[doom-module::ui ophints][ophints]]: - +: An indicator for β€œwhat did I just do?” + +This module provides op-hints (operation hinting), i.e. visual feedback for +certain operations. It highlights regions of text that the last operation (like +yank) acted on. + +Uses [[doom-package:][evil-goggles]] for evil users and [[doom-package:][volatile-highlights]] otherwise. + +*** [[doom-module::ui popup][popup]]: [[doom-module::ui popup +all][+all]] [[doom-module::ui popup +defaults][+defaults]] +: Tame sudden yet inevitable temporary windows + +This module provides a customizable popup window management system. + +Not all windows are created equally. Some are less important. Some I want gone +once they have served their purpose, like code output or a help buffer. Others I +want to stick around, like a scratch buffer or org-capture popup. + +More than that, popups ought to be the second class citizens of my editor; +spawned off to the side, discarded with the push of a button (e.g. [[kbd:][ESC]] or [[kbd:][C-g]]), +and easily restored if I want to see them again. Of course, this system should +clean up after itself and kill off buffers I mark as transient. + +*** [[doom-module::ui tabs][tabs]]: - +: Keep tabs on your buffers, literally + +This module adds an Atom-esque tab bar to the Emacs UI. + +*** [[doom-module::ui treemacs][treemacs]]: [[doom-module::ui treemacs +lsp][+lsp]] +: A sidebar for all the things + +[[doom-package:treemacs][Treemacs]] is a file and project explorer similar to NeoTree or vim's NerdTree, +but largely inspired by the Project Explorer in Eclipse. It shows the file +system outlines of your projects in a simple tree layout allowing quick +navigation and exploration, while also possessing basic file management +utilities. It includes: + +- Integration with Git (if [[doom-module:][:tools magit]] is enabled) +- Integration with Evil (if [[doom-module:][:editor evil +everywhere]] is enabled) +- Workspace awareness (if [[doom-module:][:ui workspaces]] is enabled) + +*** [[doom-module::ui unicode][unicode]]: - +: Extended unicode support for various languages + +This module extends Doom's ability to display non-English unicode. It is +primarily useful for non-English Emacs users, for whom Doom's built-in unicode +support in insufficient. + +This module relies on the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package. It tries to setup the default +emacs fontset to cover as many unicode glyphs as possible by scanning all +available glyphs from all available fonts. + +When this module is enabled: +- Emacs will prefer to use the ~doom-unicode-font~ font to display non-latin + glyphs if it provides coverage for them. +- The first time you run Emacs a unicode cache will be generated -- this will + take a while! +- The cache will be regenerated every time Emacs is made aware of new fonts or + you change the font configuration e.g. by modifying ~doom-unicode-font~. +- The cache will be stored and should not be regenerated unless font-related + configuration or the versions of relevant packages changes. + +*** [[doom-module::ui vc-gutter][vc-gutter]]: - +: Get your diff out of the gutter + +This module displays a diff of the current file (against HEAD) in the fringe. +Supports Git, Svn, Hg, and Bzr. + +*** [[doom-module::ui vi-tilde-fringe][vi-tilde-fringe]]: - +: Fringe tildes beyond EOB + +Displays a tilde(~) in the left fringe to indicate an empty line, similar to Vi. + +*** [[doom-module::ui window-select][window-select]]: [[doom-module::ui window-select +numbers][+numbers]] [[doom-module::ui window-select +switch-window][+switch-window]] +: Visually switch windows + +This module provides several methods for selecting windows without the use of +the mouse or spatial navigation (e.g. [[kbd:][C-w {h,j,k,l}]]). + +The command ~other-window~ is remapped to either [[doom-package:][switch-window]] or [[doom-package:][ace-window]], +depending on which backend you've enabled. It is bound to [[kbd:][C-x o]] (and [[kbd:][C-w C-w]] for +evil users). + +It also provides numbered windows and selection with the [[doom-package:][winum]] package, if +desired. Evil users can jump to window N in [[kbd:][C-w ]] (where N is a number between +0 and 9). Non evil users have [[kbd:][C-x w ]] instead. + +*** [[doom-module::ui workspaces][workspaces]]: - +: Tab emulation, persistence, & separate workspaces + +This module adds support for workspaces, powered by [[doom-package:][persp-mode]], as well as a API +for manipulating them. + +#+begin_quote + πŸ’‘ There are many ways to use workspaces. I spawn a workspace per task. Say I'm + working in the main workspace, when I realize there is a bug in another part + of my project. I open a new workspace and deal with it in there. In the + meantime, I need to check my email, so mu4e gets its own workspace. + + Once I've completed the task, I close the workspace and return to main. +#+end_quote + +*** [[doom-module::ui zen][zen]]: - +: Distraction-free mode for the eternally distracted + +This module provides two minor modes that make Emacs into a more comfortable +writing or coding environment. Folks familiar with "distraction-free" or "zen" +modes from other editors -- or [[doom-package:][olivetti]], [[doom-package:][sublimity]], and [[doom-package:][tabula-rasa]] (Emacs +plugins) -- will feel right at home. + +These modes are: +- ~mixed-pitch-mode~ :: + Which renders (most) text in a variable pitch font (see + ~doom-variable-pitch-font~). Unlike ~variable-pitch-mode~, this will not + affect segments of text that are intended to remain in a fixed pitch font, + such as code blocks or ASCII tables. +- ~writeroom-mode~ :: + Our all-in-one "zen" mode that will: + 1. Center the current buffer. + 2. Remove superfluous UI elements (like the modeline). + 3. Activate ~mixed-pitch-mode~. + 4. Scale up the buffer's text slightly (see ~+zen-text-scale~). + 5. And make the window's borders slightly thicker (see + ~+zen-window-divider-size~). + + diff --git a/modules/app/README.org b/modules/app/README.org new file mode 100644 index 000000000..516c9440d --- /dev/null +++ b/modules/app/README.org @@ -0,0 +1,12 @@ +# -*- mode: doom-docs-org -*- +#+title: :app +#+created: February 19, 2017 +#+since: 21.12.0 + +* Description +Application modules are complex and opinionated modules that transform Emacs +toward a specific purpose. They may have additional dependencies and *should be +loaded last* (but before [[doom-module:][:config]] modules). + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/app/calendar/README.org b/modules/app/calendar/README.org index 19dc03203..b971f459d 100644 --- a/modules/app/calendar/README.org +++ b/modules/app/calendar/README.org @@ -1,34 +1,52 @@ -#+TITLE: app/calendar -#+DATE: January 13, 2018 -#+SINCE: v2.1 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :app calendar +#+subtitle: Watch your missed deadlines in real time +#+created: January 13, 2018 +#+since: 21.12.0 (#355) -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#packages][Packages]] -- [[#configuration][Configuration]] - - [[#changing-calendar-sources][Changing calendar sources]] - - [[#synchronizing-org-and-google-calendar][Synchronizing Org and Google Calendar]] - -* Description +* Description :unfold: This module adds a calendar view for Emacs, with org and google calendar sync support. -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ ** Packages -+ [[https://github.com/kiwanami/emacs-calfw][calfw]] -+ [[https://github.com/kiwanami/emacs-calfw][calfw-org]] -+ [[https://github.com/kidd/org-gcal.el][org-gcal]] +- [[doom-package:][calfw]] +- [[doom-package:][calfw-org]] +- [[doom-package:][org-gcal]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- A Google Calendar account. +- [[https://github.com/kidd/org-gcal.el#installation][An OAuth client ID]], for syncing said account with [[doom-package:][org-gcal]]. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Changing calendar sources By defining your own calendar commands, you can control what sources to pull calendar data from: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (defun my-open-calendar () (interactive) (cfw:open-calendar-buffer @@ -41,10 +59,21 @@ calendar data from: (cfw:ical-create-source "Moon" "~/moon.ics" "Gray") ; ICS source1 (cfw:ical-create-source "gcal" "https://..../basic.ics" "IndianRed") ; google calendar ICS ))) -#+END_SRC +#+end_src The [[https://github.com/kiwanami/emacs-calfw][kiwanami/emacs-calfw]] project readme contains more examples. ** Synchronizing Org and Google Calendar The [[https://github.com/kidd/org-gcal.el][kidd/org-gcal.el]] project README contains more detailed instructions on how to link your calendar with Google calendars. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/emms/README.org b/modules/app/emms/README.org index 6741690d7..bebe425f2 100644 --- a/modules/app/emms/README.org +++ b/modules/app/emms/README.org @@ -1,71 +1,75 @@ -#+TITLE: app/emms -#+DATE: March 6, 2021 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :app emms +#+subtitle: A media player for music no one's heard of +#+created: March 06, 2021 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] - - [[#ubuntu][Ubuntu]] -- [[#troubleshooting][Troubleshooting]] - - [[#new-music-files-not-showing-up-in-database][New music files not showing up in database]] -- [[#appendix][Appendix]] - - [[#keybinds][Keybinds]] - -* Description +* Description :unfold: This module enables Emacs to be used as a music player. It uses [[https://www.musicpd.org/][mpd]] as a backend server and [[https://musicpd.org/clients/mpc/][mpc]] to update your music database. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://git.savannah.gnu.org/git/emms.git/][emms]] +** Packages +- [[doom-package:][emms]] -* Prerequisites -This module requires an active MPD server, the MPC utility, and a music library. +** Hacks +/No hacks documented for this module./ -** Arch Linux -#+BEGIN_SRC bash -pacman -S mpd mpc -#+END_SRC +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -** NixOS -#+BEGIN_SRC nix -services.mpd.enable = true; -environment.systemPackages = [ pkgs.mpc_cli ]; -#+END_SRC +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -** Ubuntu -#+BEGIN_SRC bash -apt install mpd mpc -#+END_SRC +This module requires: +- [[https://mpd.readthedocs.io/en/stable/user.html#installation][mpd]] (and a running mpd server) +- [[https://www.musicpd.org/clients/mpc/][mpc]] + +These should be available through your OS package manager. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +** Keybinds +- [[kbd:][ l]] Toggles whether or not the player repeats the playlist. +- [[kbd:][ m]] Mixes the playlist. +- [[kbd:][ i]] Insert specific song +- [[kbd:][ s]] Save the current playlist to a file +- [[kbd:][ p]] Insert playlist save into current playlist +- [[kbd:][g a]] Sort the browser by artists +- [[kbd:][g b]] Sort the browser by genre +- [[kbd:][X]] Stops the player +- [[kbd:][x]] pauses the player +- [[kbd:][D]] in the playlist window removes that item +- [[kbd:][C]] clears the playlist +- [[kbd:][>]] move five seconds forward in the current track +- [[kbd:][<]] Opposite five back +- [[kbd:][RET]] In browser adds the artist's songs to the playlist, in the playlist starts + playlist. + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -** New music files not showing up in database -Try =M-x +emms/mpd-restart-music-daemon=. If that doesn't work restart emacs. +[[doom-report:][Report an issue?]] -* Appendix -** Keybinds -+ =SPC m l= Toggles whether or not the player repeats the playlist. -+ =SPC m m= Mixes the playlist. -+ =SPC m i= Insert specific song -+ =SPC m s= Save the current playlist to a file -+ =SPC m p= Insert playlist save into current playlist -+ =g a= Sort the browser by artists -+ =g b= Sort the browser by genre -+ =X= Stops the player -+ =x= pauses the player -+ =D= in the playlist window removes that item -+ =C= clears the playlist -+ =>= move five seconds forward in the current track -+ =<= Opposite five back -+ =RET= In browser adds the artist's songs to the playlist, in the playlist starts playlist. +** New music files not showing up in database +Try [[kbd:][M-x +emms/mpd-restart-music-daemon]] then restart emacs. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/everywhere/README.org b/modules/app/everywhere/README.org index 2d75cf89b..2dd3f1530 100644 --- a/modules/app/everywhere/README.org +++ b/modules/app/everywhere/README.org @@ -1,58 +1,73 @@ -#+title: app/everywhere -#+date: February 7, 2021 -#+since: v3.0 -#+startup: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :app everywhere +#+subtitle: *leave* Emacs!? You must be joking +#+created: February 07, 2021 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - -* Description +* Description :unfold: This module adds system-wide popup Emacs windows for quick edits. ** Maintainers -+ [[https://github.com/tecosaur][@tecosaur]] +- [[doom-user:][@tecosaur]] -** Module Flags +[[doom-contrib-maintainer:][Become a maintainer?]] -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/tecosaur/emacs-everywhere][emacs-everywhere]] +** Packages +- [[doom-package:][emacs-everywhere]] -* Prerequisites +** Hacks +/No hacks documented for this module./ -On Linux =xclip=, =xdotool=, =xprop=, and =xwininfo= are needed. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -On MacOS, Emacs must be allowed to "control your computer" under *Settings > Accessibility*. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Features +This module requires: +- *On Linux:* (these should be available through your OS package manager) + - =xclip= + - =xdotool= + - =xprop= + - =xwininfo= +- *On MacOS:* that Emacs is allowed to "control your computer" under *System + Preferences > Accessibility*. +* Usage To use this, invoke the =emacs-everywhere= executable. This can be done in two ways: -+ ~emacsclient --eval "(emacs-everywhere)"~ -+ ~doom everywhere~ ++ ~$ emacsclient --eval "(emacs-everywhere)"~ ++ ~$ doom everywhere~ It is recommended that you add a keybinding for this. From here, you can edit away to your hearts content in the created frame, then -return to the original window and paste the content with =C-c C-c= or =SPC q f=. -To exit without pasting, use =C-c C-k=. +return to the original window and paste the content with [[kbd:][C-c C-c]] or [[kbd:][SPC q f]]. To +exit without pasting, use [[kbd:][C-c C-k]]. * Configuration - -=emacs-everywhere= likes to guess if you triggered it from an application which +[[doom-package:][emacs-everywhere]] likes to guess if you triggered it from an application which supports markdown. Configure ~emacs-everywhere-markdown-windows~ and ~emacs-everywhere-markdown-apps~ to improve how accurate this is on your system. -By default, when markdown is detected, ~markdown-mode~ is used. It is possible to -instead use pandoc to convert the content to Org (and export to markdown when +By default, when markdown is detected, ~markdown-mode~ is used. It is possible +to instead use pandoc to convert the content to Org (and export to markdown when closing the frame) by setting ~emacs-everywhere-major-mode-function~ to -=#'org-mode=. +~#'org-mode~. -Most other behaviour is implemented as hooks on ~emacs-everywhere-init-hooks~. +Most other behavior is implemented as hooks on ~emacs-everywhere-init-hooks~. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/irc/README.org b/modules/app/irc/README.org index 41e2983cc..9e843b7d7 100644 --- a/modules/app/irc/README.org +++ b/modules/app/irc/README.org @@ -1,82 +1,82 @@ -#+TITLE: app/irc -#+DATE: June 11, 2017 -#+SINCE: v2.0.3 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :app irc +#+subtitle: How neckbeards socialize +#+created: June 11, 2017 +#+since: 2.0.3 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#macos][macOS]] - - [[#debian--ubuntu][Debian / Ubuntu]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] -- [[#features][Features]] - - [[#an-irc-client-in-emacs][An IRC Client in Emacs]] -- [[#configuration][Configuration]] - - [[#pass-the-unix-password-manager][Pass: the unix password manager]] - - [[#emacs-auth-source-api][Emacs' auth-source API]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module turns Emacs into an IRC client, capable of OS notifications. -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/jorgenschaefer/circe][circe]] -+ [[https://github.com/eqyiel/circe-notifications][circe-notifications]] +** Module flags +/This module has no flags./ -* Prerequisites -This module requires =gnutls= for secure IRC connections to work. +** Packages +- [[doom-package:][circe]] +- [[doom-package:][circe-notifications]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- [[https://www.gnutls.org/][GnuTLS]], for secure IRC connections to work. + +This should be available through your OS package manager. ** macOS -#+BEGIN_SRC sh +#+begin_src sh brew install gnutls -#+END_SRC +#+end_src ** Debian / Ubuntu -#+BEGIN_SRC sh +#+begin_src sh apt install gnutls-bin -#+END_SRC +#+end_src ** Arch Linux -#+BEGIN_SRC sh +#+begin_src sh pacman -S gnutls -#+END_SRC +#+end_src ** NixOS -#+BEGIN_SRC nix +#+begin_src nix environment.systemPackages = [ pkgs.gnutls ]; -#+END_SRC +#+end_src -* Features -** An IRC Client in Emacs -To connect to IRC you can invoke the ~=irc~ function using =M-x= or your own -custom keybinding. +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -| command | description | -|---------+-------------------------------------------| -| ~=irc~ | Connect to IRC and all configured servers | +To connect to IRC use ~M-x =irc~. -When in a circe buffer these keybindings will be available. +When in a circe buffer these keybindings will be available: +| command | key | description | +|-----------------------------+-----------------+----------------------------------------------| +| ~+irc/tracking-next-buffer~ | [[kbd:][ a]] | Switch to the next active buffer | +| ~circe-command-JOIN~ | [[kbd:][ j]] | Join a channel | +| ~+irc/send-message~ | [[kbd:][ m]] | Send a private message | +| ~circe-command-NAMES~ | [[kbd:][ n]] | List the names of the current channel | +| ~circe-command-PART~ | [[kbd:][ p]] | Part the current channel | +| ~+irc/quit~ | [[kbd:][ Q]] | Kill the current circe session and workgroup | +| ~circe-reconnect~ | [[kbd:][ R]] | Reconnect the current server | -| command | key | description | -|-----------------------------+-----------+----------------------------------------------| -| ~+irc/tracking-next-buffer~ | =SPC m a= | Switch to the next active buffer | -| ~circe-command-JOIN~ | =SPC m j= | Join a channel | -| ~+irc/send-message~ | =SPC m m= | Send a private message | -| ~circe-command-NAMES~ | =SPC m n= | List the names of the current channel | -| ~circe-command-PART~ | =SPC m p= | Part the current channel | -| ~+irc/quit~ | =SPC m Q= | Kill the current circe session and workgroup | -| ~circe-reconnect~ | =SPC m R= | Reconnect the current server | +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration -Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument (a plist) -takes the same arguments as ~circe-network-options~. - -#+BEGIN_SRC emacs-lisp :tangle no +Use ~set-irc-server! SERVER PLIST~ to configure IRC servers. Its second argument +(a plist) takes the same arguments as ~circe-network-options~: +#+begin_src emacs-lisp ;; if you omit =:host=, ~SERVER~ will be used instead. (after! circe (set-irc-server! "irc.libera.chat" @@ -86,20 +86,23 @@ takes the same arguments as ~circe-network-options~. :sasl-username "myusername" :sasl-password "mypassword" :channels ("#emacs")))) -#+END_SRC +#+end_src However, *it is a obviously a bad idea to store your password in plaintext,* so here are ways to avoid that: -** Pass: the unix password manager +** TODO Pass: the unix password manager +#+begin_quote + πŸ”¨ /This section is outdated and needs to be rewritten./ [[doom-contrib-module:][Rewrite it?]] +#+end_quote + [[https://www.passwordstore.org/][Pass]] is my tool of choice. I use it to manage my passwords. If you activate the -[[../../../modules/tools/pass/README.org][:tools pass]] module you get an elisp API through which to access your -password store. +[[doom-module:][:tools pass]] module you get an elisp API through which to access your password +store. ~set-irc-server!~ accepts a plist can use functions instead of strings. ~+pass-get-user~ and ~+pass-get-secret~ can help here: - -#+BEGIN_SRC emacs-lisp :tangle no +#+begin_src emacs-lisp (set-irc-server! "irc.libera.chat" `(:tls t :port 6697 @@ -107,12 +110,11 @@ password store. :sasl-username ,(+pass-get-user "irc/libera.chat") :sasl-password ,(+pass-get-secret "irc/libera.chat") :channels ("#emacs"))) -#+END_SRC +#+end_src But wait, there's more! This stores your password in a public variable which could be accessed or appear in backtraces. Not good! So we go a step further: - -#+BEGIN_SRC emacs-lisp :tangle no +#+begin_src emacs-lisp (set-irc-server! "irc.libera.chat" `(:tls t :port 6697 @@ -120,12 +122,12 @@ could be accessed or appear in backtraces. Not good! So we go a step further: :sasl-username ,(+pass-get-user "irc/libera.chat") :sasl-password (lambda (&rest _) (+pass-get-secret "irc/libera.chat")) :channels ("#emacs"))) -#+END_SRC +#+end_src And you're good to go! -Note that =+pass-get-user= tries to find your username by looking for the fields -listed in =+pass-user-fields= (by default =login=, =user==, =username== and +Note that ~+pass-get-user~ tries to find your username by looking for the fields +listed in ~+pass-user-fields~ (by default =login=, =user==, =username== and =email=)=). An example configuration looks like #+begin_example @@ -136,8 +138,7 @@ username: myusername ** Emacs' auth-source API ~auth-source~ is built into Emacs. As suggested [[https://github.com/jorgenschaefer/circe/wiki/Configuration#safer-password-management][in the circe wiki]], you can store (and retrieve) encrypted passwords with it. - -#+BEGIN_SRC emacs-lisp :tangle no +#+begin_src emacs-lisp (setq auth-sources '("~/.authinfo.gpg")) (defun my-fetch-password (&rest params) @@ -159,6 +160,15 @@ username: myusername :nick "doom" :sasl-password my-nickserver-password :channels ("#emacs"))) -#+END_SRC +#+end_src * TODO Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/rss/README.org b/modules/app/rss/README.org index 2cd1f36e9..c3c2717ee 100644 --- a/modules/app/rss/README.org +++ b/modules/app/rss/README.org @@ -1,92 +1,102 @@ -#+TITLE: app/rss -#+DATE: May 12, 2020 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :app rss +#+subtitle: An RSS reader that Google can't shut down +#+created: May 12, 2020 +#+since: 2.0.9 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#without-org][Without +org]] - - [[#with-org][With +org]] - - [[#keybindings][Keybindings]] - - [[#news-filtering][News filtering]] - - [[#automatically-updating-feed-when-opening-elfeed][Automatically updating feed when opening elfeed]] -- [[#troubleshooting][Troubleshooting]] - -* Description -+ Read RSS feeds in the comfort of DOOM (Emacs) +* Description :unfold: +Read RSS feeds in the comfort of Emacs. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+org= to enable ~elfeed-org~ to use ~org-directory/elfeed.org~ +** Module flags +- +org :: + Enable [[doom-package:][elfeed-org]], so you can configure your feeds with an org file + (={org-directory}/elfeed.org=) rather than Elisp. -** Plugins -+ [[https://github.com/skeeto/elfeed][elfeed]] -+ [[https://github.com/algernon/elfeed-goodies][elfeed-goodies]] -+ =+org= - + [[https://github.com/remyhonig/elfeed-org][elfeed-org]] +** Packages +- [[doom-package:][elfeed]] +- [[doom-package:][elfeed-goodies]] +- [[doom-package:][elfeed-org]] if [[doom-module:][+org]] ** Hacks -+ By default ~elfeed-search-filter~ is set to ~@2-weeks-ago~ and makes the last 2 weeks of entries visible. This needs to be set after elfeed has loaded like so in your ~config.el~ - #+begin_src elisp -(after! elfeed - (setq elfeed-search-filter "@1-month-ago +unread")) +- By default ~elfeed-search-filter~ is set to ~@2-weeks-ago~ and makes the last + 2 weeks of entries visible. This needs to be set after elfeed has loaded like + so in your =$DOOMDIR/config.el=: + #+begin_src emacs-lisp + (after! elfeed + (setq elfeed-search-filter "@1-month-ago +unread")) #+end_src -* Prerequisites -This module has no prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Features -+ As there isn't currently binding for ~elfeed-update~ you can run it with ~M-x elfeed-update~ +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- As there isn't currently binding for ~elfeed-update~ you can run it with ~M-x + elfeed-update~ + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Without +org -When you don't want to use org mode to manage your elfeed feeds you can put your subscriptions to personal ~config.el~ file, ex: -#+BEGIN_SRC elisp +When you don't want to use org mode to manage your elfeed feeds you can put your +subscriptions in =$DOOMDIR/config.el=: +#+begin_src emacs-lisp (setq elfeed-feeds '("https://this-week-in-rust.org/rss.xml" "http://feeds.bbci.co.uk/news/rss.xml")) -#+END_SRC +#+end_src ** With +org -When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to configure feeds to follow. -#+BEGIN_SRC org +When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to +configure feeds to follow: +#+begin_src org ,* root :elfeed: ,** Programming :programming: ,*** [[https://this-week-in-rust.org/rss.xml][This Week in Rust]] :rust: ,** News :news: ,*** Top news :tops: ,**** http://feeds.bbci.co.uk/news/rss.xml -#+END_SRC -+ Root of ~elfeed-org~ needs to have ~:elfeed:~ tag. This is where ~elfeed-org~ starts to read. -+ You can have subheaders as in example ~:programming:~, and ~elfeed-org~ applies that tag to all subheader feeds, in example it adds it to ~This Week in Rust~. -+ You can "name" feeds as you please with ~org-mode~ ~org-insert-link~ (~C-c C-l~) and put name as you want into ~description~. -+ If you don't want to use ~org-directory/elfeed.org~ file you can specify it with ~(setq rmh-elfeed-org-files '("path/to/your/elfeed/file.org))~ +#+end_src +- Root of ~elfeed-org~ needs to have ~:elfeed:~ tag. This is where ~elfeed-org~ + starts to read. +- You can have subheaders as in example ~:programming:~, and ~elfeed-org~ + applies that tag to all subheader feeds, in example it adds it to ~This Week + in Rust~. +- You can "name" feeds as you please with ~org-mode~ ~org-insert-link~ ([[kbd:][C-c C-l]]) + and put name as you want into ~description~. +- If you don't want to use ~org-directory/elfeed.org~ file you can specify it + with ~(setq rmh-elfeed-org-files '("path/to/your/elfeed/file.org))~ ** Keybindings + General - | Key | Mode | Description | - |---------+--------------------+--------------------------------| - | =S-RET= | Elfeed-search-mode | Open link into browser | - | =RET= | Elfeed-search-mode | Open item | - | =s= | Elfeed-search-mode | Filter | - | =C-j= | Elfeed-show-mode | Move to next item | - | =C-k= | Elfeed-show-mode | Move to previous item | + | Key | Mode | Description | + |-------+--------------------+------------------------| + | [[kbd:][S-RET]] | elfeed-search-mode | Open link into browser | + | [[kbd:][RET]] | elfeed-search-mode | Open item | + | [[kbd:][s]] | elfeed-search-mode | Filter | + | [[kbd:][C-j]] | elfeed-show-mode | Move to next item | + | [[kbd:][C-k]] | elfeed-show-mode | Move to previous item | + If ~:editor evil +everywhere~ | Key | Description | |-----+-----------------------------| - | q | elfeed-kill-buffer | - | r | elfeed-search-update--force | - | g c | Copy link of current entry | + | [[kbd:][q]] | elfeed-kill-buffer | + | [[kbd:][r]] | elfeed-search-update--force | + | [[kbd:][g c]] | Copy link of current entry | ** News filtering + Time filtering @@ -106,9 +116,18 @@ When using ~+org~ flag then configuration is easier. You can use ~org-mode~ to c + Exclude ~!something~ ** Automatically updating feed when opening elfeed -Hook ~elfeed-update~ to ~elfeed-search-mode-hook~ -#+BEGIN_SRC elisp -(add-hook! 'elfeed-search-mode-hook 'elfeed-update) -#+END_SRC +Hook ~elfeed-update~ to ~elfeed-search-mode-hook~: +#+begin_src emacs-lisp +(add-hook 'elfeed-search-mode-hook #'elfeed-update) +#+end_src -* TODO Troubleshooting +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/app/twitter/README.org b/modules/app/twitter/README.org index 38d9694fe..24409d140 100644 --- a/modules/app/twitter/README.org +++ b/modules/app/twitter/README.org @@ -1,96 +1,102 @@ -#+TITLE: app/twitter -#+DATE: October 11, 2019 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :app twitter +#+subtitle: Be superficial in plain text +#+created: October 11, 2019 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] -- [[#appendix][Appendix]] - - [[#commands--keybindings][Commands & Keybindings]] - -* Description +* Description :unfold: Enjoy twitter from emacs. -+ View various timelines side by side, e.g. user's timeline, home, etc. -+ Post new tweets -+ Send direct messages -+ Retweet -+ Follow and un-follow users -+ Favorite tweets +- View various timelines side by side, e.g. user's timeline, home, etc. +- Post new tweets +- Send direct messages +- Retweet +- Follow and un-follow users +- Favorite tweets -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/hayamiz/twittering-mode][twittering-mode]] -+ [[https://github.com/abo-abo/avy][avy]] +** Module flags +/This module has no flags./ -** TODO Hacks -{A list of internal modifications to included packages} +** Packages +- [[doom-package:][avy]] +- [[doom-package:][twittering-mode]] -* Prerequisites +** Hacks +/No hacks documented for this module./ -+ For SSL connection (required by Twitter's API), one of the followings is required: - + [[http://curl.haxx.se/][cURL]] - + [[http://www.gnu.org/software/wget/][GNU Wget]] - + [[http://www.openssl.org/][OpenSSL]] - + [[http://www.gnu.org/software/gnutls/][GnuTLS]] -+ [[http://www.gnupg.org/][GnuPG]] is required for keeping the OAuth token encrypted in local storage. -+ ~twittering-icon-mode~ converts retrieved icons into XPM by default. To - achieve this and for displaying icons in formats that are not supported by - Emacs as well as for resizing icon images, [[http://www.imagemagick.org/][ImageMagick]] is required. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ - To build emacs with ImageMagick support the ~--with-imagemagick~ flag needs to - be passed to the ~configure~ script, e.g. ~./configure --with-imagemagick~. - For detailed instruction on how to build Emacs from source please refer to - [[https://git.savannah.gnu.org/cgit/emacs.git/tree/INSTALL][INSTALL]] in Emacs' savannah repository. -+ For keeping retrieved icons in local storage, [[http://www.gzip.org/][gzip]] is required. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* TODO Features -An in-depth list of features, how to use them, and their dependencies. +This module requires: +- One of the following (for SSL connections; required by Twitter's API): + - [[http://curl.haxx.se/][cURL]] + - [[http://www.gnu.org/software/wget/][GNU Wget]] + - [[http://www.openssl.org/][OpenSSL]] + - [[http://www.gnu.org/software/gnutls/][GnuTLS]] +- [[http://www.gnupg.org/][GnuPG]], for encrypting the OAuth token, stored locally. +- [[http://www.gzip.org/][gzip]], for compressing retrieved profile pictures, +- [[http://www.imagemagick.org/][ImageMagick]], for displaying and resizing profile pictures. + + Build Emacs with ImageMagick support using the ~--with-imagemagick~ flag ([[https://git.savannah.gnu.org/cgit/emacs.git/tree/INSTALL][how + to build Emacs from source]]). + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration -How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Troubleshooting -Currently ~twittering-mode~ binds =SPC=, breaking its functionality as a leader -key. To work around this issue you may use =M-SPC= instead when in -~twittering-mode~. - -* Appendix ** Commands & Keybindings Here is a list of available commands and their default keybindings (defined in -[[./config.el][config.el]]). - +[[./config.el][config.el]]): | command | key / ex command | description | |---------------------+------------------+-------------------------------------------------------------| -| ~+twitter/quit~ | =q= | Close current window | -| ~+twitter/quit-all~ | =Q= | Close all twitter windows and buffers, and delete workspace | - -And when ~:editor evil +everywhere~ is active: +| ~+twitter/quit~ | [[kbd:][q]] | Close current window | +| ~+twitter/quit-all~ | [[kbd:][Q]] | Close all twitter windows and buffers, and delete workspace | +And when [[doom-module:][:editor evil +everywhere]] is active: | command | key / ex command | description | |--------------------------------------------------+------------------+------------------------------------------------------------------| -| ~twittering-favorite~ | =f= | Favorite/Like a tweet | -| ~twittering-unfavorite~ | =F= | Un-favorite/Un-like a tweet | -| ~twittering-follow~ | =C-f= | Follow user | -| ~twittering-unfollow~ | =C-F= | Un-follow user | -| ~twittering-delete-status~ | =d= | Delete a tweet | -| ~twittering-retweet~ | =r= | Retweet | -| ~twittering-toggle-or-retrieve-replied-statuses~ | =R= | Toggle or retrieve replies | -| ~twittering-update-status-interactive~ | =o= | Update tweets | -| ~+twitter/ace-link~ | =O= | Open some visible link from a ~twittering-mode~ buffer using ace | -| ~twittering-search~ | =/= | Search | -| ~twittering-goto-next-status~ | =J= | Go to next tweet | -| ~twittering-goto-previous-status~ | =K= | Go to previous tweet | -| ~twittering-goto-first-status~ | =gg= | Go to first tweet | -| ~twittering-goto-last-status~ | =G= | Go to last tweet | -| ~twittering-goto-next-status-of-user~ | =gj= | Go to next tweet of user | -| ~twittering-goto-previous-status-of-user)))~ | =gk= | Go to previous tweet of user | +| ~twittering-favorite~ | [[kbd:][f]] | Favorite/Like a tweet | +| ~twittering-unfavorite~ | [[kbd:][F]] | Un-favorite/Un-like a tweet | +| ~twittering-follow~ | [[kbd:][C-f]] | Follow user | +| ~twittering-unfollow~ | [[kbd:][C-F]] | Un-follow user | +| ~twittering-delete-status~ | [[kbd:][d]] | Delete a tweet | +| ~twittering-retweet~ | [[kbd:][r]] | Retweet | +| ~twittering-toggle-or-retrieve-replied-statuses~ | [[kbd:][R]] | Toggle or retrieve replies | +| ~twittering-update-status-interactive~ | [[kbd:][o]] | Update tweets | +| ~+twitter/ace-link~ | [[kbd:][O]] | Open some visible link from a ~twittering-mode~ buffer using ace | +| ~twittering-search~ | [[kbd:][/]] | Search | +| ~twittering-goto-next-status~ | [[kbd:][J]] | Go to next tweet | +| ~twittering-goto-previous-status~ | [[kbd:][K]] | Go to previous tweet | +| ~twittering-goto-first-status~ | [[kbd:][gg]] | Go to first tweet | +| ~twittering-goto-last-status~ | [[kbd:][G]] | Go to last tweet | +| ~twittering-goto-next-status-of-user~ | [[kbd:][gj]] | Go to next tweet of user | +| ~twittering-goto-previous-status-of-user)))~ | [[kbd:][gk]] | Go to previous tweet of user | + +* Troubleshooting +[[doom-report:][Report an issue?]] + +** ~twittering-mode~ overrides the [[kbd:][SPC]] key +Currently ~twittering-mode~ binds [[kbd:][SPC]], breaking its functionality as a leader +key for evil users. To work around this issue you may use [[kbd:][M-SPC]] instead. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote + diff --git a/modules/checkers/README.org b/modules/checkers/README.org new file mode 100644 index 000000000..1cf314097 --- /dev/null +++ b/modules/checkers/README.org @@ -0,0 +1,10 @@ +# -*- mode: doom-docs-org -*- +#+title: :checkers +#+created: August 01, 2021 +#+since: 21.12.0 + +* Description +For modules dedicated to linting plain text (primarily code and prose). + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/checkers/grammar/README.org b/modules/checkers/grammar/README.org index 1f51b3e03..09afc7e8c 100644 --- a/modules/checkers/grammar/README.org +++ b/modules/checkers/grammar/README.org @@ -1,68 +1,76 @@ -#+TITLE: checkers/grammar -#+DATE: January 9, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :checkers grammar +#+subtitle: Tasing grammar mistake every you make +#+created: January 09, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#language-tool][Language Tool]] - - [[#commands][Commands]] - - [[#writegood-mode][writegood-mode]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds grammar checking to Emacs to aid your writing by combining -=lang-tool= and =writegood-mode=. +[[doom-package:][lang-tool]] and [[doom-package:][writegood-mode]]. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/mhayashi1120/Emacs-langtool][langtool]] -+ [[https://github.com/bnbeckwith/writegood-mode][writegood-mode]] +** Packages +- [[doom-package:][langtool]] +- [[doom-package:][writegood-mode]] -* Prerequisites -This module requires langtool (which requires =Java 1.8+=). +** Hacks +/No hacks documented for this module./ -It can be acquired either from https://languagetool.org/ or your OS's package -manager: +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -+ macOS: ~brew install languagetool~ -+ Arch Linux: ~pacman -S languagetool~ +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -This module tries to guess the location of languagetool-commandline.jar. If you -get a warning that Doom =couldn't find languagetool-commandline.jar=, you will -need to set ~langtool-language-tool-jar~ to its location. +This module requires [[https://languagetool.org/][LanguageTool]] (which requires =Java 1.8+=). -* Features -An in-depth list of features, how to use them, and their dependencies. +It is available from either https://languagetool.org/ or your OS's package +manager. E.g. +- macOS: ~$ brew install languagetool~ +- Arch Linux: ~$ pacman -S languagetool~ + +This module tries to guess the location of =languagetool-commandline.jar=. If +you get a warning that Doom ~couldn't find languagetool-commandline.jar~, you +will need to set ~langtool-language-tool-jar~ to its location. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote ** Language Tool [[https://www.languagetool.org/][Language Tool]] is a polyglot proofreader service that checks for grammar and stylistic issues in your writing. This requires Java 1.8+. #+begin_quote -This requires Java 1.8+ + 🚧 This requires Java 1.8+ #+end_quote *** Commands -- ~langtool-check~ -- ~langtool-correct-buffer~ +- ~M-x langtool-check~ +- ~M-x langtool-correct-buffer~ ** writegood-mode This minor mode highlights weasel words, duplication and passive voice. -* Configuration -How to configure this module, including common problems and how to address them. +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/checkers/spell/README.org b/modules/checkers/spell/README.org index b0fb6971f..5d9d99eaf 100644 --- a/modules/checkers/spell/README.org +++ b/modules/checkers/spell/README.org @@ -1,149 +1,154 @@ -#+TITLE: checkers/spell -#+DATE: February 20, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :checkers spell +#+subtitle: Tasing you for misspelling mispelling +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#aspell][Aspell]] - - [[#hunspell][Hunspell]] - - [[#enchant][Enchant]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#changing-how-quickly-spell-fu-spellchecks-after-changes][Changing how quickly spell-fu spellchecks after changes]] - - [[#spell-fu-users][Spell-fu users]] - - [[#flyspell-users][Flyspell users]] - - [[#reducing-false-positives-by-disabling-spelling-on-certain-faces][Reducing false positives by disabling spelling on certain faces]] - - [[#spell-fu-users-1][Spell-fu users]] - - [[#flyspell-users-1][Flyspell users]] - - [[#adding-or-removing-words-to-your-personal-dictionary][Adding or removing words to your personal dictionary]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This modules provides spellchecking powered by =aspell=, =hunspell= or =enchant=. +* Description :unfold: +This modules provides spellchecking powered by =aspell=, =hunspell= or +=enchant=. Spellcheck is automatically loaded in many ~text-mode~ derivatives, which includes ~org-mode~, ~markdown-mode~, the Git Commit buffer (from magit), ~mu4e-compose-mode~, and others. +- Spell checking and correction using =aspell=, =hunspell= or =enchant=. +- Ignores source code inside org or markdown files. +- Lazily spellchecking recent changes only when idle. +- Choosing suggestions using completion interfaces ([[doom-package:][ivy]] or [[doom-package:][helm]]). + ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+flyspell= Use =flyspell= instead of =spell-fu=. It's significantly slower, - but supports multiple languages and dictionaries. -+ =+aspell= Use =aspell= as a backend for correcting words. -+ =+hunspell= Use =hunspell= as a backend for correcting words. -+ =+enchant= Use =enchant-2= as a backend for correcting words. -+ =+everywhere= Spell check in programming modes as well (in comments). +** Module flags +- +aspell :: + Use =aspell= as a backend for correcting words. +- +enchant :: + Use =enchant-2= as a backend for correcting words. +- +everywhere :: + Spell check in programming modes as well (in comments only). +- +flyspell :: + Use [[doom-package:][flyspell]] instead of [[doom-package:][spell-fu]]. It's significantly slower, but supports + multiple languages and dictionaries. +- +hunspell :: + Use =hunspell= as a backend for correcting words. -** Plugins -+ if =+flyspell= - + [[https://github.com/d12frosted/flyspell-correct][flyspell-correct]] - + [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-ivy-interface][flyspell-correct-ivy]] (=completion/ivy=) - + [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-helm-interface][flyspell-correct-helm]] (=completion/helm=) - + [[https://github.com/d12frosted/flyspell-correct#flyspell-correct-popup-interface][flyspell-correct-popup]] (if *neither* =completion/ivy=, =completion/helm= or =completion/vertico=) - + [[https://github.com/rolandwalker/flyspell-lazy][flyspell-lazy]] -+ else - + [[https://gitlab.com/ideasman42/emacs-spell-fu][spell-fu]] +** Packages +- if [[doom-module:][+flyspell]] + - [[doom-package:][flyspell-correct]] + - [[doom-package:][flyspell-correct-ivy]] if [[doom-module:][:completion ivy]] + - [[doom-package:][flyspell-correct-helm]] if [[doom-module:][:completion helm]] + - [[doom-package:][flyspell-correct-popup]] unless [[doom-module:][:completion ivy]], [[doom-module:][:completion helm]], or + [[doom-module:][:completion vertico]] + - [[doom-package:][flyspell-lazy]] +- else + - [[doom-package:][spell-fu]] -* Prerequisites -This module requires one of =aspell=, =hunspell= or =enchant-2= -installed on your system and in your ~PATH~. -They also need dictionaries for your language(s). +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires one of =aspell=, =hunspell= or =enchant-2= installed on +your system and in your =$PATH=. They also need dictionaries for your +language(s). #+begin_quote -If you *are not* using =+flyspell=, you will need aspell (and a dictionary) -installed whether or not you have =+hunspell= or =+enchant= enabled. -This is because =spell-fu= does not support generating the word list -with anything other than =aspell= yet. + 🚧 If you *are not* using [[doom-module:][+flyspell]], you will need =aspell= (and a dictionary) + installed whether or not you have [[doom-module:][+hunspell]] or [[doom-module:][+enchant]] enabled. This is + because [[doom-package:][spell-fu]] does not support generating the word list with anything + other than =aspell= yet. #+end_quote ** Aspell -+ Ubuntu: ~apt-get install aspell aspell-en~ -+ macOS: ~brew install aspell~ -+ Arch Linux: ~pacman -S aspell aspell-en~ -+ NixOS: - #+BEGIN_SRC nix +- Ubuntu: ~$ apt-get install aspell aspell-en~ +- macOS: ~$ brew install aspell~ +- Arch Linux: ~$ pacman -S aspell aspell-en~ +- NixOS: + #+begin_src nix { environment.systemPackages = with pkgs; [ (aspellWithDicts (dicts: with dicts; [ en en-computers en-science ])) ]; } - #+END_SRC + #+end_src ** Hunspell -+ Ubuntu: ~apt-get install hunspell~ -+ macOS: ~brew install hunspell~ -+ Arch Linux: ~pacman -S hunspell~ -+ NixOS: - #+BEGIN_SRC nix +- Ubuntu: ~$ apt-get install hunspell~ +- macOS: ~$ brew install hunspell~ +- Arch Linux: ~$ pacman -S hunspell~ +- NixOS: + #+begin_src nix { environment.systemPackages = with pkgs; [ hunspell ]; } - #+END_SRC + #+end_src ** Enchant -+ Ubuntu: ~apt-get install enchant-2~ -+ macOS: ~brew install enchant~ -+ Arch Linux: ~pacman -S enchant~ -+ NixOS: - #+BEGIN_SRC nix +- Ubuntu: ~$ apt-get install enchant-2~ +- macOS: ~$ brew install enchant~ +- Arch Linux: ~$ pacman -S enchant~ +- NixOS: + #+begin_src nix { environment.systemPackages = with pkgs; [ enchant ]; } - #+END_SRC + #+end_src - Enchant is just a wrapper for other spelling libraries - and you will need to have at least one of the supported backends installed as well. + Enchant is just a wrapper for other spelling libraries and you will need to + have at least one of the supported backends installed as well. -* Features -+ Spell checking and correction using =aspell=, =hunspell= or =enchant=. -+ Ignores source code inside org or markdown files. -+ Lazily spellchecking recent changes only when idle. -+ Choosing suggestions using completion interfaces (=ivy= or =helm=). +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -When using =+everywhere=, spell checking is performed for as many major modes as +When using [[doom-module:][+everywhere]], spell checking is performed for as many major modes as possible, and not only ~text-mode~ derivatives. e.g. in comments for programming major modes. -* Configuration -Dictionary is set by =ispell-dictionary= variable. Can be changed locally with -the function =ispell-change-dictionary=. +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -** Changing how quickly spell-fu spellchecks after changes +Dictionary is set by ~ispell-dictionary~ variable. Can be changed locally with +the function ~ispell-change-dictionary~. + +** Changing how quickly spelling is checked after changes *** Spell-fu users Adjust ~spell-fu-idle-delay~ to change how long Emacs waits to spellcheck after -recent changes. -#+BEGIN_SRC elisp +recent changes: +#+begin_src emacs-lisp (after! spell-fu (setq spell-fu-idle-delay 0.5)) ; default is 0.25 -#+END_SRC +#+end_src *** Flyspell users -Lazy spellcheck is provided by =flyspell-lazy= package. +Lazy spellcheck is provided by [[doom-package:][flyspell-lazy]] package. -=flyspell-lazy-idle-seconds= sets how many idle seconds until spellchecking -recent changes (default as 1), while =flyspell-lazy-window-idle-seconds= sets -how many seconds until the whole window is spellchecked (default as 3). -#+BEGIN_SRC elisp +~flyspell-lazy-idle-seconds~ sets how many idle seconds until spellchecking +recent changes (default as 1), while ~flyspell-lazy-window-idle-seconds~ sets +how many seconds until the whole window is spellchecked (default as 3): +#+begin_src emacs-lisp (after! flyspell (setq flyspell-lazy-idle-seconds 2)) -#+END_SRC +#+end_src ** Reducing false positives by disabling spelling on certain faces *** Spell-fu users Users can exclude what faces to preform spellchecking on by adjusting ~+spell-excluded-faces-alist~ in a buffer-local hook: -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (setf (alist-get 'markdown-mode +spell-excluded-faces-alist) '(markdown-code-face markdown-reference-face @@ -153,18 +158,19 @@ Users can exclude what faces to preform spellchecking on by adjusting markdown-html-attr-value-face markdown-html-attr-name-face markdown-html-tag-name-face)) -#+END_SRC +#+end_src *** Flyspell users -Flyspell will run a series of predicate functions to determine if a word should be spell checked. You can add your own with ~set-flyspell-predicate!~: -#+BEGIN_SRC elisp +Flyspell will run a series of predicate functions to determine if a word should +be spell checked. You can add your own with ~set-flyspell-predicate!~: +#+begin_src emacs-lisp (set-flyspell-predicate! '(markdown-mode gfm-mode) #'+markdown-flyspell-word-p) -#+END_SRC +#+end_src Flyspell predicates take no arguments and must return a boolean to determine if the word at point should be spell checked. For example: -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (defun +markdown-flyspell-word-p () "Return t if point is on a word that should be spell checked. @@ -183,13 +189,46 @@ Return nil if on a link url, markup, html, or references." for face in faces if (memq face unsafe-faces) return t))))) -#+END_SRC +#+end_src ** Adding or removing words to your personal dictionary Use ~M-x +spell/add-word~ and ~M-x +spell/remove-word~ to whitelist words that -you know are not misspellings. For evil users these are bound to =zg= and =zw=, -respectively. =+flyspell= users can also add/remove words from the -~flyspell-correct~ popup interface (there will be extra options on the list of +you know are not misspellings. For evil users these are bound to [[kbd:][zg]] and [[kbd:][zw]], +respectively. [[doom-module:][+flyspell]] users can also add/remove words from the +[[doom-package:][flyspell-correct]] popup interface (there will be extra options on the list of corrections for "save word to dictionary"). -* TODO Troubleshooting +* Troubleshooting +[[doom-report:][Report an issue?]] + +** spell-fu highlights every single word +[[doom-package:][spell-fu]] caches its word list. If it was activated before your dictionaries were +installed, it will generate an empty word list, causing it to highlight all +words as incorrect. Delete its cache files in =$EMACSDIR/.local/etc/spell-fu/= +to fix this. + +** Cannot add [word] to any active dictionary +*** Aspell +If ~M-x +spell/add-word~ results in the above error this mean that the +personal dictionary file was not created for some reason. This can be +fixed by creating the required file manually. +#+begin_example shell +mkdir -p ~/.emacs.d/.local/etc/ispell +echo personal_ws-1.1 en 0 > ~/.emacs.d/.local/etc/ispell/.pws +#+end_example + +Where ~personal_ws-1.1 en 0~ is the required header format for the personal +dictionary file. ~en~ is the language you're writing in and have a dict +installed and ~0~ is the number of added words in the dictionary. If you are +planning of updating the file with the list of words, update the number +accordingly. + +After the file is created, restart emacs and adding words should work. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/checkers/syntax/README.org b/modules/checkers/syntax/README.org index 08c9b136d..09371f0c7 100644 --- a/modules/checkers/syntax/README.org +++ b/modules/checkers/syntax/README.org @@ -1,66 +1,84 @@ -#+TITLE: checkers/syntax -#+DATE: February 20, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :checkers syntax +#+subtitle: Tasing you for every semicolon you forget +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This module provides syntax checking and error highlighting, powered by [[https://github.com/flycheck/flycheck][flycheck]] - -+ If possible, include a brief list of feature highlights here -+ Like code completion, syntax checking or available snippets -+ Include links to packages & external things where possible +* Description :unfold: +This module provides syntax checking and error highlighting, powered by +[[doom-package:][flycheck]]. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+childframe= Enables displaying completion candidates in a child frame, rather than an overlay or tooltip (among with other UI enhancements). +** Module flags +- +childframe :: + Display errors/warnings in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or tooltip. + *Requires GUI Emacs.* - -** Plugins -+ [[https://github.com/flycheck/flycheck][flycheck]] -+ [[https://github.com/flycheck/flycheck-popup-tip][flycheck-popup-tip]] -+ =+childframe= - + [[https://github.com/alexmurray/flycheck-posframe][flycheck-posframe]] +** Packages +- [[doom-package:][flycheck]] +- [[doom-package:][flycheck-popup-tip]] +- [[doom-package:][flycheck-posframe]] if [[doom-module:][+childframe]] ** Hacks -If =lsp-ui-mode= is active, most of the aesthetic functionality of this module is turned off, as they show the same information. +- If ~lsp-ui-mode~ is active, most of the aesthetic functionality of this module + is turned off, as they show the same information. -* Prerequisites -This module has no direct prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -However, some major modes may require a specific linter or program to work, and some major modes may not work at all. The best way to find these dependencies is by either reading the documentation for that module, or running =doom doctor=. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has no direct requirements, but some languages may have their own +requirements to fulfill before you get syntax checking in them (and some +languages may lack syntax checking support altogether). Run ~$ doom doctor~ to +find out if you're missing any dependencies. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +Most of flycheck's features are under [[kbd:][C-c !]], regardless of whether evil mode is +used. -* Features -Most of flycheck's features are under =C-c !=, regardless of whether evil mode is used. | Keybind | Description | -| C-c ! ? | Describe Checker ] | -| C-c ! c | Check syntax in buffer | -| C-c ! l | List errors | -| C-c ! n | Next Error | -| C-c ! p | Previous error | -| C-c ! C | Clear all errors in buffer | -| C-c ! e | Explain error at point | -| C-c ! h | Display all errors at point | +|---------+-----------------------------| +| [[kbd:][C-c ! ?]] | Describe Checker | +| [[kbd:][C-c ! c]] | Check syntax in buffer | +| [[kbd:][C-c ! l]] | List errors | +| [[kbd:][C-c ! n]] | Next Error | +| [[kbd:][C-c ! p]] | Previous error | +| [[kbd:][C-c ! C]] | Clear all errors in buffer | +| [[kbd:][C-c ! e]] | Explain error at point | +| [[kbd:][C-c ! h]] | Display all errors at point | -Evil Specific +Evil Specific: | Keybind | Description | -| SPC t f | Toggle Flycheck | -| SPC c x | List errors | -| ] e | Next error | -| [ e | Prevous error | +|---------+-----------------| +| [[kbd:][SPC t f]] | Toggle Flycheck | +| [[kbd:][SPC c x]] | List errors | +| [[kbd:][] e]] | Next error | +| [[kbd:][[ e]] | Prevous error | * TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting +* Troubleshooting +[[doom-report:][Report an issue?]] + +- Use ~M-x flycheck-verify-setup~ to determine what checkers are available in a + buffer and whether they're active or not (and why). + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/README.org b/modules/completion/README.org new file mode 100644 index 000000000..5c4ffeb68 --- /dev/null +++ b/modules/completion/README.org @@ -0,0 +1,19 @@ +# -*- mode: doom-docs-org -*- +#+title: :completion +#+created: July 29, 2021 +#+since: 21.12.0 + +* Description +These modules provide interfaces and frameworks completion, including code +completion. + +* Frequently asked questions +** Should I choose Ivy, Helm, Vertico, or Ido? +:PROPERTIES: +:ID: 4f36ae11-1da8-4624-9c30-46b764e849fc +:END: +Vertico is Doom's default and comes highly recommended of the four. It is the +fastest, best integrated in Doom's ecosystem, and its module is the most +actively maintained of the four. It also has the cleanest codebase and ties into +native functionality already existing in Emacs, rather than reinventing the +wheel. diff --git a/modules/completion/company/README.org b/modules/completion/company/README.org index 7e581ca31..8b91c9a1e 100644 --- a/modules/completion/company/README.org +++ b/modules/completion/company/README.org @@ -1,92 +1,103 @@ -#+TITLE: completion/company -#+DATE: February 19, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :completion company +#+subtitle: The ultimate code completion backend +#+created: February 19, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#code-completion][Code completion]] - - [[#vim-esque-omni-completion-prefix-c-x][Vim-esque omni-completion prefix (C-x)]] -- [[#configuration][Configuration]] - - [[#enable-company-backends-in-certain-modes][Enable company backend(s) in certain modes]] -- [[#troubleshooting][Troubleshooting]] - - [[#x-mode-doesnt-have-code-completion-support-or-requires-extra-setup][X-mode doesn't have code completion support or requires extra setup.]] - - [[#no-backends-or-the-incorrect-ones-have-been-registered-for-x-mode][No backends (or the incorrect ones) have been registered for X-mode.]] - -* Description -This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. It is required -for code completion in many of Doom's :lang modules. +* Description :unfold: +This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. Many of Doom's +[[doom-module:][:lang]] modules require it for "intellisense" functionality. https://assets.doomemacs.org/completion/company/overlay.png -** Module Flags -+ =+childframe= Enables displaying completion candidates in a child frame, - rather than an overlay or tooltip (among with other UI enhancements). *This - requires GUI Emacs 26.1+ and is incompatible with the =+tng= flag* -+ =+tng= Enables completion using only ~TAB~. Pressing ~TAB~ will select the - next completion suggestion, while ~S-TAB~ will select the previous one. *This - is incompatible with the =+childframe= flag* +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ [[https://github.com/company-mode/company-mode][company-mode]] -+ [[https://github.com/hlissner/emacs-company-dict][company-dict]] -+ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=) +[[doom-contrib-maintainer:][Become a maintainer?]] -* Prerequisites -This module has no direct prerequisites. +** Module flags +- +childframe :: + Display completion candidates in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or + tooltip. *Requires GUI Emacs.* +- +tng :: + Invoke completion on [[kbd:][TAB]] instad of [[kbd:][C-SPC]]. When company is active, [[kbd:][TAB]] and + [[kbd:][S-TAB]] will navigate the completion candidates. -However, some major modes may require additional setup for code completion to -work in them. Some major modes may have no completion support at all. Check that -major mode's module's documentation for details. +** Packages +- [[doom-package:][company-box]] if [[doom-module:][+childframe]] +- [[doom-package:][company-dict]] +- [[doom-package:][company-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has no direct requirements, but some languages may have their own +requirements to fulfill before you get code completion in them (and some +languages may lack code completion support altogether). Run ~$ doom doctor~ to +find out if you're missing any dependencies. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** Code completion By default, completion is triggered after a short idle period or with the -=C-SPC= key. While the popup is visible, the following keys are available: +[[kbd:][C-SPC]] key. While the popup is visible, the following keys are available: | Keybind | Description | |---------+------------------------------------------| -| =C-n= | Go to next candidate | -| =C-p= | Go to previous candidate | -| =C-j= | (evil) Go to next candidate | -| =C-k= | (evil) Go to previous candidate | -| =C-h= | Display documentation (if available) | -| =C-u= | Move to previous page of candidates | -| =C-d= | Move to next page of candidates | -| =C-s= | Filter candidates | -| =C-S-s= | Search candidates with helm/ivy | -| =C-SPC= | Complete common | -| =TAB= | Complete common or select next candidate | -| =S-TAB= | Select previous candidate | +| [[kbd:][C-n]] | Go to next candidate | +| [[kbd:][C-p]] | Go to previous candidate | +| [[kbd:][C-j]] | (evil) Go to next candidate | +| [[kbd:][C-k]] | (evil) Go to previous candidate | +| [[kbd:][C-h]] | Display documentation (if available) | +| [[kbd:][C-u]] | Move to previous page of candidates | +| [[kbd:][C-d]] | Move to next page of candidates | +| [[kbd:][C-s]] | Filter candidates | +| [[kbd:][C-S-s]] | Search candidates with helm/ivy | +| [[kbd:][C-SPC]] | Complete common | +| [[kbd:][TAB]] | Complete common or select next candidate | +| [[kbd:][S-TAB]] | Select previous candidate | ** Vim-esque omni-completion prefix (C-x) In the spirit of Vim's omni-completion, the following insert mode keybinds are available to evil users to access specific company backends: +| Keybind | Description | +|---------+-----------------------------------| +| [[kbd:][C-x C-]]​] | Complete etags | +| [[kbd:][C-x C-f]] | Complete file path | +| [[kbd:][C-x C-k]] | Complete from dictionary/keyword | +| [[kbd:][C-x C-l]] | Complete full line | +| [[kbd:][C-x C-o]] | Invoke complete-at-point function | +| [[kbd:][C-x C-n]] | Complete next symbol at point | +| [[kbd:][C-x C-p]] | Complete previous symbol at point | +| [[kbd:][C-x C-s]] | Complete snippet | +| [[kbd:][C-x s]] | Complete spelling suggestions | -| Keybind | Description | -|-----------+-----------------------------------| -| =C-x C-]= | Complete etags | -| =C-x C-f= | Complete file path | -| =C-x C-k= | Complete from dictionary/keyword | -| =C-x C-l= | Complete full line | -| =C-x C-o= | Invoke complete-at-point function | -| =C-x C-n= | Complete next symbol at point | -| =C-x C-p= | Complete previous symbol at point | -| =C-x C-s= | Complete snippet | -| =C-x s= | Complete spelling suggestions | +** Searching with multiple keywords +If the =vertico= module is enabled, users can perform code completion with multiple search keywords with an ampersand =&=. +More information can be found [[https://github.com/oantolin/orderless#company][here]]. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Enable company backend(s) in certain modes The ~set-company-backend!~ function exists for setting ~company-backends~ buffer-locally in MODES, which is either a major-mode symbol, a minor-mode symbol, or a list of either. BACKENDS are prepended to ~company-backends~ for those modes. -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (after! js2-mode (set-company-backend! 'js2-mode 'company-tide 'company-yasnippet)) @@ -97,20 +108,18 @@ those modes. (after! cc-mode (set-company-backend! 'c-mode '(:separate company-irony-c-headers company-irony))) -#+END_SRC +#+end_src To unset the backends for a particular mode, pass ~nil~ to it: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (after! sh-script (set-company-backend! 'sh-mode nil)) -#+END_SRC +#+end_src * Troubleshooting -If code completion isn't working for you, consider the following common causes -before you file a bug report: +[[doom-report:][Report an issue?]] -** X-mode doesn't have code completion support or requires extra setup. +** X-mode doesn't have code completion support or requires extra setup There is no guarantee your language mode will have completion support. Some, like ~lua-mode~, don't have completion support in Emacs at all. Others may @@ -120,11 +129,19 @@ requires that you have a Robe server running (~M-x robe-start~). Check the relevant module's documentation for this kind of information. -** No backends (or the incorrect ones) have been registered for X-mode. -Doom expects every mode to have an explicit list of company-backends (and as +** No backends (or the incorrect ones) have been registered for X-mode +Doom expects every mode to have an explicit list of ~company-backends~ (and as short a list as possible). This may mean you aren't getting all the completion you want or any at all. -Check the value of ~company-backends~ (=SPC h v company-backends=) from that -mode to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for -details on changing what backends are available for that mode. +Check the value of ~company-backends~ ([[kbd:][SPC h v company-backends]]) from that mode +to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for details +on changing what backends are available for that mode. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/helm/README.org b/modules/completion/helm/README.org index 17ae807e7..d9ded2241 100644 --- a/modules/completion/helm/README.org +++ b/modules/completion/helm/README.org @@ -1,169 +1,183 @@ -#+TITLE: completion/helm -#+DATE: January 22, 2021 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :completion helm +#+subtitle: A tank for hunting a house fly +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#jump-to-navigation][Jump-to navigation]] - - [[#project-search--replace][Project search & replace]] - - [[#search][Search]] - - [[#replace][Replace]] - - [[#in-buffer-searching][In-buffer searching]] - - [[#helm-integration-for-various-completing-commands][Helm integration for various completing commands]] - - [[#general][General]] - - [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]] - - [[#search-1][Search]] -- [[#configuration][Configuration]] - - [[#icons][Icons]] - - [[#posframe][Posframe]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module provides Helm integration for a variety of Emacs commands, as well +as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep][Ripgrep]]. -* Description -This module provides Helm integration for a variety of Emacs commands, as well as -a unified interface for project search and replace, powered by ripgrep. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] +** Module flags +- +childframe :: + Display Helm windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires + GUI Emacs.* +- +fuzzy :: + Enable fuzzy completion for Helm searches. +- +icons :: + Display icons on completion results (where possible) using either + [[doom-package:][all-the-icons]] or [[doom-package:][treemacs]] iconsets. + +** Packages +- [[doom-package:][helm]] +- [[doom-package:][helm-company]] +- [[doom-package:][helm-c-yasnippet]] +- [[doom-package:][helm-descbinds]] +- [[doom-package:][helm-describe-modes]] +- [[doom-package:][helm-flx]]* if [[doom-module:][+fuzzy]] +- [[doom-package:][helm-icons]]* if [[doom-module:][+icons]] +- [[doom-package:][helm-org]]* if [[doom-module:][:lang org]] +- [[doom-package:][helm-posframe]]* if [[doom-module:][+childframe]] +- [[doom-package:][helm-projectile]] +- [[doom-package:][helm-rg]] +- [[doom-package:][helm-swiper]] + +** TODO Hacks #+begin_quote -I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's -lighter, simpler and faster in many cases. + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] #+end_quote -Ivy is considered a first-class citizen in Doom, however it is still possible to use Helm if you so desire. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -** Module Flags -+ =+fuzzy= Enables fuzzy completion for Helm searches. -+ =+childframe= Causes Helm to display in a floating child frame, above Emacs. -+ =+icons= Enables icons (supports both =all-the-icons= and =treemacs= icons) +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -** Plugins -+ [[https://github.com/emacs-helm/helm][helm]] -+ [[https://github.com/microamp/helm-rg][helm-rg]] -+ [[https://github.com/emacs-jp/helm-c-yasnippet][helm-c-yasnippet]] -+ [[https://github.com/tuhdo/helm-company][helm-company]] -+ [[https://github.com/emacs-helm/helm-describe-modes][helm-describe-modes]] -+ [[https://github.com/bbatsov/helm-projectile][helm-projectile]] -+ [[https://github.com/abo-abo/swiper-helm][helm-swiper]] -+ [[https://github.com/emacs-helm/helm-descbinds][helm-descbinds]] -+ [[https://github.com/PythonNut/helm-flx][helm-flx]]* (=+fuzzy=) -+ [[https://github.com/tumashu/helm-posframe][helm-posframe]]* (=+childframe=) -+ [[https://github.com/emacs-helm/helm-org][helm-org]]* (=:lang org=) -+ [[https://github.com/yyoncho/helm-icons][helm-icons]]* (=+icons=) +This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of +Doom itself, so you should already have it installed. -* Prerequisites -This module has no prerequisites. +Otherwise, Helm provides many commands to interface with a variety of programs +from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These programs are optional +for this module, but must be installed if you intend to use their associated +Helm command or plugin. -* Features -Much like Ivy, Helm is a /large/ framework and as such -covering everything is not in scope, however a number -of Doom-specific features are shown below: +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +Much like [[doom-package:][ivy]] and [[doom-package:][vertico]], [[doom-package:][helm]] is a /large/ framework. Covering all its +features is not within the scope of this module's documentation, so only its +highlights will be covered here. ** Jump-to navigation -Similar to Ivy, this module provides an interface to -navigate within a project using =projectile=: - +Similar to Ivy, this module provides an interface to navigate within a project +using [[doom-package:][projectile]]: | Keybind | Description | |------------------+-------------------------------------| -| =SPC p f=, =SPC SPC= | Jump to file in project | -| =SPC f f=, =SPC .= | Jump to file from current directory | -| =SPC s i= | Jump to symbol in file | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory | +| [[kbd:][SPC s i]] | Jump to symbol in file | ** Project search & replace -This module also provides interacetive text search and replace using ripgrep +This module also provides interactive text search and replace using ripgrep. *** Search - | Keybind | Description | |---------+--------------------------| -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u= +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | + +Prefixing these keys with the universal argument ([[kbd:][SPC u]] for evil users; [[kbd:][C-u]] otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files. This module also provides Ex Commands for evil users: - | Ex command | Description | |------------------------+------------------------------------------------------------------| | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | | ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) | -The optional `!` is equivalent to the universal argument for the previous +The optional ~!~ is equivalent to the universal argument for the previous commands. *** Replace - These keybindings are available while a search is active: +| Keybind | Description | +|---------+-----------------------------------------------| +| [[kbd:][C-c C-o]] | Open a buffer with your search results | +| [[kbd:][C-c C-e]] | Open a writable buffer of your search results | +| [[kbd:][C-SPC]] | Preview the current candidate | +| [[kbd:][C-RET]] | Open the selected candidate in other-window | -| Keybind | Description | -|-----------+-----------------------------------------------| -| =C-c C-o= | Open a buffer with your search results | -| =C-c C-e= | Open a writable buffer of your search results | -| =C-SPC= | Preview the current candidate | -| =C-RET= | Open the selected candidate in other-window | - -Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed -with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil -users). +Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with +[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). ** In-buffer searching -The =swiper= package provides an interactive buffer search powered by helm. It -can be invoked with: +The [[doom-package:][swiper]] package provides an interactive buffer search powered by helm. It can +be invoked with: +- [[kbd:][SPC s s]] (~swiper-isearch~) +- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~) +- [[kbd:][SPC s b]] (~swiper~) +- ~:sw[iper] [QUERY]~ -+ =SPC s s= (~swiper-isearch~) -+ =SPC s S= (~swiper-isearch-thing-at-point~) -+ =SPC s b= (~swiper~) -+ ~:sw[iper] [QUERY]~ +A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]]. -A wgrep buffer can be opened from swiper with =C-c C-e=. ** Helm integration for various completing commands Helm also has a number of overrides for built-in functionality: *** General | Keybind | Description | |------------+---------------------------| -| =M-x=, =SPC := | Smarter, smex-powered M-x | -| =SPC '= | Resume last ivy session | +| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x | +| [[kbd:][SPC ']] | Resume last ivy session | *** Jump to files, buffers or projects | Keybind | Description | |------------------+---------------------------------------| -| =SPC RET= | Find bookmark | -| =SPC f f=, =SPC .= | Browse from current directory | -| =SPC p f=, =SPC SPC= | Find file in project | -| =SPC f r= | Find recently opened file | -| =SPC p p= | Open another project | -| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | -| =SPC b B=, =SPC <= | Switch to buffer | +| [[kbd:][SPC RET]] | Find bookmark | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project | +| [[kbd:][SPC f r]] | Find recently opened file | +| [[kbd:][SPC p p]] | Open another project | +| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace | +| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer | *** Search | Keybind | Description | |---------+-------------------------------------------| -| =SPC p t= | List all TODO/FIXMEs in project | -| =SPC s b= | Search the current buffer | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -| =SPC s i= | Search for symbol in current buffer | -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s s= | Search the current buffer (incrementally) | +| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project | +| [[kbd:][SPC s b]] | Search the current buffer | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | +| [[kbd:][SPC s i]] | Search for symbol in current buffer | +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s s]] | Search the current buffer (incrementally) | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Icons -Icons are now included, and support 2 providers ([[https://github.com/domtronn/all-the-icons.el][all-the-icons]] and [[https://github.com/Alexander-Miller/treemacs][treemacs]]). -By default, to maintain consistency we use =all-the-icons=; however if you wish -to modify this you can do so using the below snippet: +Icon support is now included, through one of two providers: [[doom-package:][all-the-icons]] and +[[doom-package:][treemacs]]. By default, to maintain consistency we use [[doom-package:][all-the-icons]]; however if +you wish to modify this you can do so using the below snippet: #+begin_src emacs-lisp (after! helm (setq helm-icons-provider 'treemacs)) #+end_src -** Posframe +** TODO Posframe * Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/ido/README.org b/modules/completion/ido/README.org new file mode 100644 index 000000000..2ea0e17bd --- /dev/null +++ b/modules/completion/ido/README.org @@ -0,0 +1,57 @@ +# -*- mode: doom-docs-org -*- +#+title: :completion ido +#+subtitle: A foil for other search engines +#+created: February 20, 2017 +#+since: 2.0.0 + +* Description :unfold: +Interactive DO things. The completion engine that is /mostly/ built-into Emacs. + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][crm-custom]] +- [[doom-package:][flx-ido]] +- [[doom-package:][ido-completing-read+]] +- [[doom-package:][ido-sort-mtime]] +- [[doom-package:][ido-vertical-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/ido/config.el b/modules/completion/ido/config.el index bced27ee5..5ca00607b 100644 --- a/modules/completion/ido/config.el +++ b/modules/completion/ido/config.el @@ -9,7 +9,6 @@ (use-package! ido :hook (doom-first-input . ido-mode) - :hook (ido-mode . ido-everywhere) :hook (ido-mode . ido-ubiquitous-mode) :preface ;; HACK `ido' is a really old package. It defines `ido-mode' manually and @@ -29,7 +28,8 @@ ido-confirm-unique-completion t ido-case-fold t ido-create-new-buffer 'always - ido-enable-flex-matching t) + ido-enable-flex-matching t + ido-everywhere t) (map! :map (ido-common-completion-map ido-file-completion-map) "C-w" #'ido-delete-backward-word-updir diff --git a/modules/completion/ivy/README.org b/modules/completion/ivy/README.org index 878070e01..15cdf6d38 100644 --- a/modules/completion/ivy/README.org +++ b/modules/completion/ivy/README.org @@ -1,28 +1,10 @@ -#+TITLE: completion/ivy -#+DATE: February 13, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :completion ivy +#+subtitle: Yesterday's lightest search engine +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#jump-to-navigation][Jump-to navigation]] - - [[#project-search--replace][Project search & replace]] - - [[#in-buffer-searching][In-buffer searching]] - - [[#ivy-integration-for-various-completing-commands][Ivy integration for various completing commands]] - - [[#general][General]] - - [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]] - - [[#search][Search]] -- [[#configuration][Configuration]] - - [[#enable-fuzzynon-fuzzy-search-for-specific-commands][Enable fuzzy/non-fuzzy search for specific commands]] - - [[#change-the-position-of-the-ivy-childframe][Change the position of the ivy childframe]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module provides Ivy integration for a variety of Emacs commands, as well as a unified interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]]. @@ -31,63 +13,87 @@ I prefer ivy over ido for its flexibility. I prefer ivy over helm because it's lighter, simpler and faster in many cases. #+end_quote -** Module Flags -+ =+fuzzy= Enables fuzzy completion for Ivy searches. -+ =+prescient= Enables prescient filtering and sorting for Ivy searches. -+ =+childframe= Causes Ivy to display in a floating child frame, above Emacs. -+ =+icons= Enables file icons for switch-{buffer,project}/find-file counsel - commands. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/abo-abo/swiper][ivy]] -+ [[https://github.com/abo-abo/swiper][counsel]] -+ [[https://github.com/ericdanan/counsel-projectile][counsel-projectile]] -+ [[https://github.com/abo-abo/swiper][swiper]] -+ [[https://github.com/abo-abo/swiper][ivy-hydra]] -+ [[https://github.com/yevgnen/ivy-rich][ivy-rich]] -+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] -+ [[https://github.com/DarwinAwardWinner/amx][amx]] -+ [[https://github.com/lewang/flx][flx]]* (=+fuzzy=) -+ [[https://github.com/raxod502/prescient.el][prescient]]* (=+prescient=) -+ [[https://github.com/tumashu/ivy-posframe][ivy-posframe]]* (=+childframe=) -+ [[https://github.com/asok/all-the-icons-ivy][all-the-icons-ivy]]* (=+icons=) +** Module flags +- +childframe :: + Display Ivy windows in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an popup buffer. *Requires + GUI Emacs.* +- +fuzzy :: + Enable fuzzy completion for Ivy searches. +- +icons :: + Enable file icons for switch-{buffer,project}/find-file commands. +- +prescient :: + Enable prescient filtering and sorting for Ivy searches. + +** Packages +- [[doom-package:][all-the-icons-ivy]]* if [[doom-module:][+icons]] +- [[doom-package:][amx]] +- [[doom-package:][counsel]] +- [[doom-package:][counsel-projectile]] +- [[doom-package:][flx]]* if [[doom-module:][+fuzzy]] +- [[doom-package:][ivy]] +- [[doom-package:][ivy-hydra]] +- [[doom-package:][ivy-posframe]]* if [[doom-module:][+childframe]] +- [[doom-package:][ivy-rich]] +- [[doom-package:][prescient]]* if [[doom-module:][+prescient]] +- [[doom-package:][swiper]] +- [[doom-package:][wgrep]] ** Hacks -+ Functions with ivy/counsel equivalents have been globally remapped (like +- Functions with ivy/counsel equivalents have been globally remapped (like ~find-file~ => ~counsel-find-file~). So a keybinding to ~find-file~ will invoke ~counsel-find-file~ instead. -+ ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex +- ~counsel-[arp]g~'s 3-character limit was reduced to 1 (mainly for the ex command) -* Prerequisites -This module has no prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Features -Ivy and its ilk are large plugins. Covering everything about them is outside of -this documentation's scope, so only Doom-specific Ivy features are listed here: +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]], which is a hard dependency of +Doom itself, so you should already have it installed. + +Otherwise, Counsel (an Ivy plugin) provides many commands to interface with a +variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ more. These +programs are optional for this module, but must be installed if you intend to +use their associated Helm command or plugin. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +[[doom-package:][ivy]] is a /large/ framework for completing things. Covering all its features is +not within the scope of this module's documentation, so only its highlights will +be covered here. ** Jump-to navigation Inspired by Sublime Text's jump-to-anywhere, CtrlP/Unite in Vim, and Textmate's -Command-T, this module provides similar functionality by bringing ~projectile~ -and ~ivy~ together. +Command-T, this module provides similar functionality by bringing [[doom-package:][projectile]] and +[[doom-package:][ivy]] together. https://assets.doomemacs.org/completion/ivy/projectile.png -| Keybind | Description | -|----------------------+-------------------------------------| -| =SPC p f=, =SPC SPC= | Jump to file in project | -| =SPC f f=, =SPC .= | Jump to file from current directory | -| =SPC s i= | Jump to symbol in file | +| Keybind | Description | +|------------------+-------------------------------------| +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory | +| [[kbd:][SPC s i]] | Jump to symbol in file | ** Project search & replace This module provides interactive text search and replace using ripgrep. -| Keybind | Description | -|-----------+--------------------------| -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | +| Keybind | Description | +|---------+--------------------------| +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | https://assets.doomemacs.org/completion/ivy/search.png @@ -96,7 +102,6 @@ otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files. This module also provides Ex Commands for evil users: - | Ex command | Description | |------------------------+------------------------------------------------------------------| | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | @@ -108,65 +113,79 @@ commands. ----- These keybindings are available while a search is active: +| Keybind | Description | +|---------+-----------------------------------------------| +| [[kbd:][C-c C-o]] | Open a buffer with your search results | +| [[kbd:][C-c C-e]] | Open a writable buffer of your search results | +| [[kbd:][C-SPC]] | Preview the current candidate | +| [[kbd:][C-RET]] | Open the selected candidate in other-window | -| Keybind | Description | -|-----------+-----------------------------------------------| -| =C-c C-o= | Open a buffer with your search results | -| =C-c C-e= | Open a writable buffer of your search results | -| =C-SPC= | Preview the current candidate | -| =C-RET= | Open the selected candidate in other-window | - -Changes to the resulting wgrep buffer (opened by =C-c C-e=) can be committed -with =C-c C-c= and aborted with =C-c C-k= (alternatively =ZZ= and =ZQ=, for evil -users). +Changes to the resulting wgrep buffer (opened by [[kbd:][C-c C-e]]) can be committed with +[[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] (alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). https://assets.doomemacs.org/completion/ivy/search-replace.png ** In-buffer searching -The =swiper= package provides an interactive buffer search powered by ivy. It +The [[doom-package:][swiper]] package provides an interactive buffer search powered by ivy. It can be invoked with: -+ =SPC s s= (~swiper-isearch~) -+ =SPC s S= (~swiper-isearch-thing-at-point~) -+ =SPC s b= (~swiper~) -+ ~:sw[iper] [QUERY]~ +- [[kbd:][SPC s s]] (~swiper-isearch~) +- [[kbd:][SPC s S]] (~swiper-isearch-thing-at-point~) +- [[kbd:][SPC s b]] (~swiper~) +- ~:sw[iper] [QUERY]~ https://assets.doomemacs.org/completion/ivy/swiper.png -A wgrep buffer can be opened from swiper with =C-c C-e=. +A wgrep buffer can be opened from swiper with [[kbd:][C-c C-e]]. ** Ivy integration for various completing commands *** General -| Keybind | Description | -|----------------+---------------------------| -| =M-x=, =SPC := | Smarter, smex-powered M-x | -| =SPC '= | Resume last ivy session | +| Keybind | Description | +|------------+---------------------------| +| [[kbd:][M-x]], [[kbd:][SPC :]] | Smarter, smex-powered M-x | +| [[kbd:][SPC ']] | Resume last ivy session | *** Jump to files, buffers or projects -| Keybind | Description | -|----------------------+---------------------------------------| -| =SPC RET= | Find bookmark | -| =SPC f f=, =SPC .= | Browse from current directory | -| =SPC p f=, =SPC SPC= | Find file in project | -| =SPC f r= | Find recently opened file | -| =SPC p p= | Open another project | -| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | -| =SPC b B=, =SPC <= | Switch to buffer | +| Keybind | Description | +|------------------+---------------------------------------| +| [[kbd:][SPC RET]] | Find bookmark | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project | +| [[kbd:][SPC f r]] | Find recently opened file | +| [[kbd:][SPC p p]] | Open another project | +| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace | +| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer | *** Search -| Keybind | Description | -|-----------+-------------------------------------------| -| =SPC p t= | List all TODO/FIXMEs in project | -| =SPC s b= | Search the current buffer | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -| =SPC s i= | Search for symbol in current buffer | -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s s= | Search the current buffer (incrementally) | +| Keybind | Description | +|---------+-------------------------------------------| +| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project | +| [[kbd:][SPC s b]] | Search the current buffer | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | +| [[kbd:][SPC s i]] | Search for symbol in current buffer | +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s s]] | Search the current buffer (incrementally) | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** TODO Enable fuzzy/non-fuzzy search for specific commands ** TODO Change the position of the ivy childframe * TODO Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/completion/vertico/README.org b/modules/completion/vertico/README.org index 5b2ddebca..933557217 100644 --- a/modules/completion/vertico/README.org +++ b/modules/completion/vertico/README.org @@ -1,73 +1,66 @@ -#+TITLE: completion/vertico -#+DATE: July 25, 2021 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :completion vertico +#+subtitle: Tomorrow's search engine +#+created: July 25, 2021 +#+since: 21.12.0 (#4664) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#vertico-keybindings][Vertico keybindings]] - - [[#jump-to-navigation][Jump-to navigation]] - - [[#project-search--replace][Project search & replace]] - - [[#in-buffer-searching][In-buffer searching]] - - [[#vertico-integration-for-various-completing-commands][Vertico integration for various completing commands]] - - [[#general][General]] - - [[#jump-to-files-buffers-or-projects][Jump to files, buffers or projects]] - - [[#search][Search]] - - [[#file-path-completion][File Path Completion]] - - [[#consult][Consult]] - - [[#multiple-candidate-search][Multiple candidate search]] - - [[#async-search-commands][Async search commands]] - - [[#marginalia][Marginalia]] - - [[#orderless-filtering][Orderless filtering]] -- [[#configuration][Configuration]] - - [[#vertico][Vertico]] - - [[#consult-1][Consult]] - - [[#marginalia-1][Marginalia]] - - [[#embark][Embark]] - -* Description +* Description :unfold: This module enhances the Emacs search and completion experience, and also provides a united interface for project search and replace, powered by [[https://github.com/BurntSushi/ripgrep/][ripgrep]]. It does this with several modular packages focused on enhancing the built-in ~completing-read~ interface, rather than replacing it with a parallel ecosystem -like =ivy= and =helm= do. The primary packages are: +like [[doom-package:][ivy]] and [[doom-package:][helm]] do. The primary packages are: -+ Vertico, which provides the vertical completion user interface -+ Consult, which provides a suite of useful commands using ~completing-read~ -+ Embark, which provides a set of minibuffer actions -+ Marginalia, which provides annotations to completion candidates -+ Orderless, which provides better filtering methods +- Vertico, which provides the vertical completion user interface +- Consult, which provides a suite of useful commands using ~completing-read~ +- Embark, which provides a set of minibuffer actions +- Marginalia, which provides annotations to completion candidates +- Orderless, which provides better filtering methods ** Maintainers -+ @iyefrat +- [[doom-user:][@iyefrat]] -** Module Flags -+ =+icons= Adds icons to =file= and =buffer= category completion selections. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/minad/vertico][vertico]] -+ [[https://github.com/minad/consult][consult]] -+ [[https://github.com/oantolin/embark/][embark]] -+ [[https://github.com/oantolin/embark/][embark-consult]] -+ [[https://github.com/minad/marginalia][marginalia]] -+ [[https://github.com/oantolin/orderless][orderless]] -+ [[https://github.com/mhayashi1120/Emacs-wgrep][wgrep]] -+ [[https://github.com/minad/consult/][consult-flycheck]] (=:checkers syntax=) -+ [[https://github.com/iyefrat/all-the-icons-completion][all-the-icons-completion]] (=+icons=) +** Module flags +- +icons :: + Add icons to =file= and =buffer= category completion selections. -* Prerequisites -Some of the advanced filtering features in async =consult= commands require -=grep= and =ripgrep= to be built with support for [[https://www.pcre.org/][PCRE]] lookahead, see [[#async-search-commands][Async -search commands]] for more information. You can check if this is true for your -machine by running ~doom doctor~. +** Packages +- [[doom-package:][all-the-icons-completion]] if [[doom-module:][+icons]] +- [[doom-package:][consult]] +- [[doom-package:][consult-flycheck]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][embark]] +- [[doom-package:][embark-consult]] +- [[doom-package:][marginalia]] +- [[doom-package:][orderless]] +- [[doom-package:][vertico]] +- [[doom-package:][wgrep]] -* Features +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has only one requirement: [[https://github.com/BurntSushi/ripgrep][Ripgrep]] (built with [[https://www.pcre.org/][PCRE]] support; run ~$ +doom doctor~ to determine if your build meets this requirement), which is a hard +dependency of Doom itself, so you should already have it installed. + +Otherwise, Consult (a plugin this module installs) provides many commands to +interface with a variety of programs from [[https://github.com/junegunn/fzf][fzf]] to [[https://kapeli.com/dash][Dash docsets]] to [[https://www.passwordstore.org/][pass]] and /much/ +more. These programs are optional for this module, but must be installed if you +intend to use their associated Helm command or plugin. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote The packages in this module modify and use the built-in ~completing-read~ function, which is used by any function that requires completion. Due to this @@ -79,118 +72,117 @@ Doom-specific additions: When in an active Vertico completion session, the following doom added keybindings are available: -| Keybind | Description | -|-----------------------+-------------------------------------------------------------------------------| -| =C-k= | (evil) Go to previous candidate | -| =C-j= | (evil) Go to next candidate | -| =C-M-k= | (evil) Go to previous group | -| =C-M-j= | (evil) Go to next group | -| =C-;= or = a= | Open an ~embark-act~ menu to chose a useful action | -| =C-c C-;= | ~embark-export~ the current candidate list (export to a type-specific buffer) | -| =C-c C-l= | ~embark-collect~ the current candidate list (collect verbatim) | -| =C-SPC= | Preview the current candidate | +| Keybind | Description | +|-------------------+----------------------------------------------------------------| +| [[kbd:][C-k]] | (evil) Go to previous candidate | +| [[kbd:][C-j]] | (evil) Go to next candidate | +| [[kbd:][C-M-k]] | (evil) Go to previous group | +| [[kbd:][C-M-j]] | (evil) Go to next group | +| [[kbd:][C-;]] or [[kbd:][ a]] | Open an ~embark-act~ menu to chose a useful action | +| [[kbd:][C-c C-;]] | export the current candidate list to a buffer | +| [[kbd:][C-c C-l]] | ~embark-collect~ the current candidate list (collect verbatim) | +| [[kbd:][C-SPC]] | Preview the current candidate | ~embark-act~ will prompt you with a =which-key= menu with useful commands on the selected candidate or candidate list, depending on the completion category. Note -that you can press =C-h= instead of choosing a command to filter through the +that you can press [[kbd:][C-h]] instead of choosing a command to filter through the options with a Vertico buffer, that also has slightly more detailed descriptions due to Marginalia annotations. ** Jump-to navigation This module provides an interface to navigate within a project using -=projectile=: +[[doom-package:][projectile]]: https://assets.doomemacs.org/completion/vertico/projectile.png -| Keybind | Description | -|----------------------+-------------------------------------| -| =SPC p f=, =SPC SPC= | Jump to file in project | -| =SPC f f=, =SPC .= | Jump to file from current directory | -| =SPC s i= | Jump to symbol in file | +| Keybind | Description | +|------------------+-------------------------------------| +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Jump to file in project | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Jump to file from current directory | +| [[kbd:][SPC s i]] | Jump to symbol in file | ** Project search & replace This module provides interactive text search and replace using ripgrep. -| Keybind | Description | -|-----------+--------------------------| -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | +| Keybind | Description | +|---------+--------------------------| +| [[kbd:][ s p]] | Search project | +| [[kbd:][ s P]] | Search another project | +| [[kbd:][ s d]] | Search this directory | +| [[kbd:][ s D]] | Search another directory | https://assets.doomemacs.org/completion/vertico/search.png -Prefixing these keys with the universal argument (=SPC u= for evil users; =C-u= +Prefixing these keys with the universal argument ([[kbd:][SPC u]] for evil users; [[kbd:][C-u]] otherwise) changes the behavior of these commands, instructing the underlying search engine to include ignored files. This module also provides Ex Commands for evil users: - -| Ex command | Description | -|------------------------+------------------------------------------------------------------| +| Ex command | Description | +|----------------------+----------------------------------------------------------------| | ~:pg[rep][!] [QUERY]~ | Search project (if ~!~, include hidden files) | | ~:pg[rep]d[!] [QUERY]~ | Search from current directory (if ~!~, don't search recursively) | -The optional `!` is equivalent to the universal argument for the previous +The optional ~!~ is equivalent to the universal argument for the previous commands. ----- On top of the usual Vertico keybindings, search commands also offer support for -exporting the current candidate list to an editable buffer =C-c C-e=. After -editing the changes can be committed with =C-c C-c= and aborted with =C-c C-k= -(alternatively =ZZ= and =ZQ=, for evil users). It uses =wgrep= for grep -searches, =wdired= for file searches, and =occur= for buffer searches. +exporting the current candidate list to an editable buffer [[kbd:][C-c C-e]]. After +editing the changes can be committed with [[kbd:][C-c C-c]] and aborted with [[kbd:][C-c C-k]] +(alternatively [[kbd:][ZZ]] and [[kbd:][ZQ]], for evil users). It uses [[doom-package:][wgrep]] for grep searches, +[[doom-package:][wdired]] for file searches, and =occur= for buffer searches. https://assets.doomemacs.org/completion/vertico/search-replace.png ** In-buffer searching This module provides some in buffer searching bindings: -+ =SPC s s= (~isearch~) -+ =SPC s S= (~+vertico/search-symbol-at-point~ via ~consult-line~) -+ =SPC s b= (~consult-line~) +- [[kbd:][SPC s s]] (~isearch~) +- [[kbd:][SPC s S]] (~+vertico/search-symbol-at-point~ via ~consult-line~) +- [[kbd:][SPC s b]] (~consult-line~) https://assets.doomemacs.org/completion/vertico/buffer-search.png -An ~occur-edit~ buffer can be opened from ~consult-line~ with =C-c C-e=. +An ~occur-edit~ buffer can be opened from ~consult-line~ with [[kbd:][C-c C-e]]. ** Vertico integration for various completing commands *** General -| Keybind | Description | -|----------------+-----------------------------| -| =M-x=, =SPC := | Enhanced M-x | -| =SPC '= | Resume last Vertico session | +| Keybind | Description | +|------------+-----------------------------| +| [[kbd:][M-x]], [[kbd:][SPC :]] | Enhanced M-x | +| [[kbd:][SPC ']] | Resume last Vertico session | *** Jump to files, buffers or projects -| Keybind | Description | -|----------------------+---------------------------------------| -| =SPC RET= | Find bookmark | -| =SPC f f=, =SPC .= | Browse from current directory | -| =SPC p f=, =SPC SPC= | Find file in project | -| =SPC f r= | Find recently opened file | -| =SPC p p= | Open another project | -| =SPC b b=, =SPC ,= | Switch to buffer in current workspace | -| =SPC b B=, =SPC <= | Switch to buffer | +| Keybind | Description | +|------------------+---------------------------------------| +| [[kbd:][SPC RET]] | Find bookmark | +| [[kbd:][SPC f f]], [[kbd:][SPC .]] | Browse from current directory | +| [[kbd:][SPC p f]], [[kbd:][SPC SPC]] | Find file in project | +| [[kbd:][SPC f r]] | Find recently opened file | +| [[kbd:][SPC p p]] | Open another project | +| [[kbd:][SPC b b]], [[kbd:][SPC ,]] | Switch to buffer in current workspace | +| [[kbd:][SPC b B]], [[kbd:][SPC <]] | Switch to buffer | -=SPC b b= and =SPC ,= support changing the workspace you're selecting a buffer from +[[kbd:][SPC b b]] and [[kbd:][SPC ,]] support changing the workspace you're selecting a buffer from via [[https://github.com/minad/consult#narrowing-and-grouping][Consult narrowing]], e.g. if you're on the first workspace, you can switch to -selecting a buffer from the third workspace by typing =3 SPC= into the prompt, -or the last workspace by typing =0 SPC=. +selecting a buffer from the third workspace by typing [[kbd:][3 SPC]] into the prompt, or +the last workspace by typing [[kbd:][0 SPC]]. -=SPC f f= and =SPC .= support exporting to a =wdired= buffer using =C-c C-e=. +[[kbd:][SPC f f]] and [[kbd:][SPC .]] support exporting to a [[kbd:][wdired]] buffer using [[kbd:][C-c C-e]]. *** Search -| Keybind | Description | -|-----------+-------------------------------------------| -| =SPC p t= | List all TODO/FIXMEs in project | -| =SPC s b= | Search the current buffer | -| =SPC s d= | Search this directory | -| =SPC s D= | Search another directory | -| =SPC s i= | Search for symbol in current buffer | -| =SPC s p= | Search project | -| =SPC s P= | Search another project | -| =SPC s s= | Search the current buffer (incrementally) | +| Keybind | Description | +|---------+-------------------------------------------| +| [[kbd:][SPC p t]] | List all TODO/FIXMEs in project | +| [[kbd:][SPC s b]] | Search the current buffer | +| [[kbd:][SPC s d]] | Search this directory | +| [[kbd:][SPC s D]] | Search another directory | +| [[kbd:][SPC s i]] | Search for symbol in current buffer | +| [[kbd:][SPC s p]] | Search project | +| [[kbd:][SPC s P]] | Search another project | +| [[kbd:][SPC s s]] | Search the current buffer (incrementally) | *** File Path Completion Note that Emacs allows you to switch directories with shadow paths, for example @@ -206,17 +198,20 @@ This module modifies the default keybindings used in ~consult-completing-read-multiple~: | Keybind | Description | |---------+-------------------------------------------------------------| -| =TAB= | Select or deselect current candidate | -| =RET= | Enters selected candidates (also toggles current candidate) | +| [[kbd:][TAB]] | Select or deselect current candidate | +| [[kbd:][RET]] | Enters selected candidates (also toggles current candidate) | *** Async search commands +:PROPERTIES: +:ID: 4ab16bf0-f9e8-4798-8632-ee7b13d2291e +:END: Consult async commands (e.g. ~consult-ripgrep~) will have a preceding separator -character (usually =#=) before the search input. This is known as the =perl= +character (usually ~#~) before the search input. This is known as the =perl= splitting style. Input typed after the separator will be fed to the async command until you type a second seperator, afterwhich the candidate list will be -filtered with Emacs instead (and can be filtered using =orderless=, for -example). The specific seperator character can be changed by editing it, and -might be different if the initial input already contains =#=. +filtered with Emacs instead (and can be filtered using [[doom-package:][orderless]], for example). +The specific seperator character can be changed by editing it, and might be +different if the initial input already contains =#=. Note that grep-like async commands translate the input (between the first and second =#=) to an Orderless-light expression: space separated inputs are all @@ -229,11 +224,11 @@ For more information [[https://github.com/minad/consult#asynchronous-search][see ** Marginalia | Keybind | Description | |---------+---------------------------------| -| =M-A= | Cycle between annotation levels | +| [[kbd:][M-A]] | Cycle between annotation levels | -Marginalia annotations for symbols (e.g. =SPC h f= and =SPC h v=) come with -extra information the nature of the symbol. For the meaning of the annotations -see ~marginalia--symbol-class~. +Marginalia annotations for symbols (e.g. [[kbd:][SPC h f]] and [[kbd:][SPC h v]]) come with extra +information the nature of the symbol. For the meaning of the annotations see +~marginalia--symbol-class~. ** Orderless filtering When using orderless to filter through candidates, the default behaviour is for @@ -246,40 +241,62 @@ first matched candidate as input. Filtering further is instead achieved by pressing space and entering another input. In essence, when trying to match =foobar.org=, instead of option 1., use option 2.: -1. (BAD) Enter =foo TAB=, completes to =foobar.=, enter =org RET= -2. (GOOD) Enter =foo SPC org RET= +1. (BAD) Enter ~foo TAB~, completes to =foobar.=, enter ~org RET~ +2. (GOOD) Enter ~foo SPC org RET~ -Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more finegrained filtering, which +Doom has some builtin [[https://github.com/oantolin/orderless#style-dispatchers][style dispatchers]] for more fine-grained filtering, which you can use to further specify each space separated input in the following ways: -| Input | Description | -|------------------+----------------------------------------------| -| =!foo= | match without literal input =foo= | -| =%foo= or =foo%= | perform ~char-fold-to-regexp~ on input =foo= | -| =`foo= or =foo`= | match input =foo= as an initialism | -| ==foo= or =foo== | match only with literal input =foo= | -| =~foo= or =foo~= | match input =foo= with fuzzy/flex matching | +| Input | Description | +|--------------+------------------------------------------| +| ~!foo~ | match without literal input =foo= | +| ~%foo~ or ~foo%~ | perform ~char-fold-to-regexp~ on input =foo= | +| ~`foo~ or ~foo`~ | match input =foo= as an initialism | +| ~=foo~ or ~foo=~ | match only with literal input =foo= | +| ~~foo~ or ~foo~~ | match input =foo= with fuzzy/flex matching | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +If you want to further configure this module, here are some good places to +start: -* Configuration -If you want to further configure this module, here are some good places to start: ** Vertico Vertico provides several [[https://github.com/minad/vertico#extensions][extentions]] that can be used to extend it's interface + ** Consult Much of the behaviour of Consult commands can be changed with ~consult-customize~. The =vertico= module already does this, if you want to override the module's modifications, do: #+begin_src emacs-lisp (setq consult--read-config nil) -(consult-customize -;... -) +(consult-customize ...) #+end_src -If you are changing the preview key (set to =C-SPC=), remember to change the + +If you are changing the preview key (set to [[kbd:][C-SPC]]), remember to change the binding on ~vertico-map~ as well, as the binding there gets previews to work to an extent on non-consult commands as well. + ** Marginalia You can add more Marginalia annotation levels and change the existing ones by - editing ~marginalia-annotator-registry~ +editing ~marginalia-annotator-registry~ + ** Embark You can change the available commands in Embark for category ~$cat~ by editing - ~embark-$cat-map~, and even add new categories. Note that you add categories - by defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them. +~embark-$cat-map~, and even add new categories. Note that you add categories by +defining them [[https://github.com/minad/marginalia/#adding-custom-annotators-or-classifiers][through marginalia]], and embark picks up on them. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** Helm vs Ivy vs Ido vs Vertico +See [[id:4f36ae11-1da8-4624-9c30-46b764e849fc][this answer]]. + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/config/README.org b/modules/config/README.org new file mode 100644 index 000000000..99ca66cb5 --- /dev/null +++ b/modules/config/README.org @@ -0,0 +1,11 @@ +# -*- mode: doom-docs-org -*- +#+title: :config +#+created: July 29, 2021 +#+since: 21.12.0 + +* Description +Modules in this category provide sane defaults or improve your ability to +configure Emacs. It is best to load these last. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/config/default/README.org b/modules/config/default/README.org index 3a431c035..044d14841 100644 --- a/modules/config/default/README.org +++ b/modules/config/default/README.org @@ -1,44 +1,69 @@ -#+TITLE: :config default +# -*- mode: doom-docs-org -*- +#+title: :config default +#+subtitle: Reasonable defaults for reasonable people +#+created: February 14, 2018 +#+since: 2.0.9 +* Description :unfold: This module provides a set of reasonable defaults, including: -+ A Spacemacs-esque keybinding scheme -+ Extra Ex commands for evil-mode users -+ A yasnippet snippets library tailored to Doom emacs -+ A configuration for (almost) universally repeating searches with =;= and =,= +- A Spacemacs-inspired keybinding scheme +- A configuration for (almost) universally repeating searches with [[kbd:][;]] and [[kbd:][,]] +- A [[doom-package:][smartparens]] configuration for smart completion of certain delimiters, like + ~/* */~ command blocks in C-languages, ~~ tags in PHP, or ~def end~ in + Ruby/Crystal/etc. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +bindings :: ... +- +smartparens :: ... + +** Packages +- [[doom-package:][avy]] +- [[doom-package:][drag-stuff]] +- [[doom-package:][link-hint]] +- [[doom-package:][expand-region]] unless [[doom-module:][:editor evil]] + +** Hacks +- ~epa-pinentry-mode~ is set to ~'loopback~, forcing gpg-agent to use the Emacs + minibuffer when prompting for your passphrase. *Only works with GPG 2.1+!* + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage #+begin_quote -The defaults module is intended as a "reasonable-defaults" module, but also as a -reference for your own private modules. You'll find [[https://github.com/hlissner/doom-emacs-private][my private module in a -separate repo]]. - -Refer to the [[https://github.com/hlissner/doom-emacs/wiki/Customization][Customization page]] on the wiki for details on starting your own -private module. + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] #+end_quote -* Table of Contents :TOC: -- [[#install][Install]] -- [[#configuration][Configuration]] - - [[#im-not-an-evil-user][I'm not an evil user...]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] - - [[#hacks][Hacks]] +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* Install -This module has no external dependencies. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] -* Configuration -** I'm not an evil user... -That's fine. All evil configuration is ignored if =:editor evil= is disabled. +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]] +#+end_quote -* Appendix ** Commands -+ ~+default/browse-project~ -+ ~+default/browse-templates~ -+ ~+default/find-in-templates~ -+ ~+default/browse-notes~ -+ ~+default/find-in-notes~ -+ ~+default/find-in-snippets~ -** Hacks -+ ~epa-pinentry-mode~ is set to ~'loopback~, forcing gpg-agent to use the Emacs - minibuffer when prompting for your passphrase. *Only works with GPG 2.1+!* +- ~+default/browse-project~ +- ~+default/browse-templates~ +- ~+default/find-in-templates~ +- ~+default/browse-notes~ +- ~+default/find-in-notes~ +- ~+default/find-in-snippets~ diff --git a/modules/config/literate/README.org b/modules/config/literate/README.org index 59421fb48..af25bc673 100644 --- a/modules/config/literate/README.org +++ b/modules/config/literate/README.org @@ -1,106 +1,125 @@ -#+TITLE: config/literate -#+DATE: May 4, 2020 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :config literate +#+subtitle: Disguise your config as poor documentation +#+created: May 28, 2020 +#+since: 2.0.9 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#change-the-location-of-configorg][Change the location of config.org]] - - [[#change-where-src-blocks-are-tangled-or-prevent-it-entirely][Change where src blocks are tangled or prevent it entirely]] -- [[#troubleshooting][Troubleshooting]] - - [[#how-to-tangle-to-doomdirinitel][How to tangle to =DOOMDIR/init.el=]] - - [[#how-to-disable-tangle-on-save][How to disable tangle-on-save]] - -* Description +* Description :unfold: This module enables support for a literate config. -A literate config consists of a =DOOMDIR/config.org=. All src blocks within are -tangled =DOOMDIR/config.el=, by default, when ~doom sync~ is executed. +A literate config consists of a =$DOOMDIR/config.org=. All src blocks within are +tangled =$DOOMDIR/config.el=, by default, when ~$ doom sync~ is executed. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -This module installs no plugins. +** Packages +/This module doesn't install any packages./ -* Prerequisites -This module has no prerequisites. +** Hacks +/No hacks documented for this module./ -* Features -+ Automatically tangles ~config.org~ to ~config.el~ when saving. See - Troubleshooting section belong on how to disable it. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module only requires a =$DOOMDIR/config.org=, which will be tangled into +=$DOOMDIR/config.el= when you run ~$ doom sync~. + +#+begin_quote + 🚧 *Be careful!* Enabling this module will overwrite =$DOOMDIR/config.el=! If + you are only trying out the module, *back up this file first!* +#+end_quote + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- Automatically tangles =$DOOMDIR/config.org= to =$DOOMDIR/config.el= when + saving. See [[*Troubleshooting][Troubleshooting]] section belong on how to disable it. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Change the location of config.org The ~+literate-config-file~ variable controls where to look for your config.org. -To change this it must be modified early -- in =DOOMDIR/init.el= or -=DOOMDIR/cli.el=. +To change this it must be modified early -- in =$DOOMDIR/init.el= or +=$DOOMDIR/cli.el=. Source blocks needs to be in some language to be automatically tangled, for -example ~#+BEGIN_SRC elisp~, but it doesn't matter what language is used. All -blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax +example ~#+begin_src emacs-lisp~, but it doesn't matter what language is used. +All blocks are tangled to ~config.el~, but ~elisp~ gives correct syntax highlighting. If you don't want to specify language in block you can also -enforce tangling by adding ~#+BEGIN_SRC :tangle yes~ +enforce tangling by adding ~#+begin_src :tangle yes~ ** Change where src blocks are tangled or prevent it entirely By default, this module tangles all src emacs-lisp blocks to config.el unless otherwise specified. -To specify otherwise use the =:tangle= parameter to: - +To specify otherwise use the ~:tangle~ parameter to: - Specify a destination other than config.el: ~:tangle packages.el~ - Disable tangling of the block altogether with ~:tangle no~ - Or force non-elisp src blocks to tangle somewhere For example: -#+BEGIN_SRC org -,#+BEGIN_SRC elisp :tangle no +#+begin_src org +,#+begin_src emacs-lisp :tangle no (message "Don't tangle me") -,#+END_SRC +,#+end_src -,#+BEGIN_SRC elisp :tangle packages.el +,#+begin_src emacs-lisp :tangle packages.el (package! my-package) (package! other-package) -,#+END_SRC +,#+end_src -,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755) +,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :tangle-mode (identity #o755) #!/usr/bin/env bash echo Hello world -,#+END_SRC +,#+end_src -,#+BEGIN_SRC sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash" +,#+begin_src sh :tangle ~/.dotfiles/bin/script.sh :shebang "#!/usr/bin/env bash" echo Hello world -,#+END_SRC -#+END_SRC +,#+end_src +#+end_src You'll find more information about babel src blocks and what parameters they -support [[https://orgmode.org/manual/Working-with-Source-Code.html][in the manual]]. +support [[https://orgmode.org/manual/Working-with-Source-Code.html][in the Org manual]]. * Troubleshooting -** How to tangle to =DOOMDIR/init.el= +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** How do I tangle to =$DOOMDIR/init.el=? If your literate needs are more complex (e.g. you want to make your init.el -literate), this module won't cut it. =init.el= is loaded long before -=config.org= is tangled in the ~doom sync~ process. +literate), this module won't cut it. =init.el= files in modules are loaded long +before =config.org= is tangled in the ~$ doom sync~ process. However, Doom comes with a [[file:../../../bin/org-tangle][bin/org-tangle]] script which can be used to tangle arbitrary org files from the command line. Use it to create your own compilation workflows. This is /much/ faster than using ~org-babel-load-file~ directly to load your literate config every time Doom is started. -** How to disable tangle-on-save +** How do I disable tangle-on-save? There are occasions where tangling on save may be undesirable. Maybe it's too slow, produces too much noise, or happens too often (on unrelated org files in -your =DOOMDIR=). This behavior can be disabled with: -#+BEGIN_SRC elisp -;; add to DOOMDIR/config.el +your =$DOOMDIR=). This behavior can be disabled with: +#+begin_src emacs-lisp +;; add to $DOOMDIR/config.el (remove-hook 'org-mode-hook #'+literate-enable-recompile-h) -#+END_SRC +#+end_src + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/README.org b/modules/editor/README.org new file mode 100644 index 000000000..307973e6b --- /dev/null +++ b/modules/editor/README.org @@ -0,0 +1,10 @@ +# -*- mode: doom-docs-org -*- +#+title: :editor +#+created: July 30, 2021 +#+since: 21.12.0 + +* Description +For modules concerned with the insertion and editing of text. Amen. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/editor/evil/README.org b/modules/editor/evil/README.org index 42470287d..de83bc827 100644 --- a/modules/editor/evil/README.org +++ b/modules/editor/evil/README.org @@ -1,114 +1,114 @@ -#+TITLE: editor/evil -#+DATE: February 2, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :editor evil +#+subtitle: The text editor Emacs was missing +#+created: April 08, 2020 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#ported-vim-plugins][Ported vim plugins]] - - [[#custom-text-objects][Custom Text Objects]] - - [[#custom-ex-commands][Custom Ex Commands]] -- [[#configuration][Configuration]] - - [[#removing-evil-mode][Removing evil-mode]] - - [[#restoring-old-substitution-behavior-on-ss][Restoring old substitution behavior on s/S]] - - [[#restoring-old-y-behavior-yank-the-whole-line][Restoring old Y behavior (yank the whole line)]] - - [[#disabling-cursor-movement-when-exiting-insert-mode][Disabling cursor movement when exiting insert mode]] +* Description :unfold: +This holy module brings the Vim editing model to Emacs. -* Description -This holy module brings the vim experience to Emacs. +** Maintainers +- [[doom-user:][@hlissner]] -** Module Flags -+ =+everywhere= Enables evilified keybinds everywhere possible. Uses the - [[https://github.com/emacs-evil/evil-collection][evil-collection]] plugin as a foundation. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/emacs-evil/evil][evil]] -+ [[https://github.com/wcsmith/evil-args][evil-args]] -+ [[https://github.com/PythonNut/evil-easymotion][evil-easymotion]] -+ [[https://github.com/cute-jumper/evil-embrace.el][evil-embrace]] -+ [[https://github.com/syl20bnr/evil-escape][evil-escape]] -+ [[https://github.com/Dewdrops/evil-exchange][evil-exchange]] -+ [[https://github.com/TheBB/evil-indent-plus][evil-indent-plus]] -+ [[https://github.com/edkolev/evil-lion][evil-lion]] -+ [[https://github.com/redguardtoo/evil-nerd-commenter][evil-nerd-commentary]] -+ [[https://github.com/cofi/evil-numbers][evil-numbers]] -+ [[https://github.com/noctuid/evil-textobj-anyblock][evil-textobj-anyblock]] -+ [[https://github.com/hlissner/evil-snipe][evil-snipe]] -+ [[https://github.com/emacs-evil/evil-surround][evil-surround]] -+ [[https://github.com/alexmurray/evil-vimish-fold][evil-vimish-fold]] -+ [[https://github.com/bling/evil-visualstar][evil-visualstar]] -+ [[https://github.com/ninrod/exato][exato]] -+ [[https://github.com/emacs-evil/evil-collection][evil-collection]]* -+ [[https://www.github.com/rgrinberg/evil-quick-diff][evil-quick-diff]] +** Module flags +- +everywhere :: + Enable evilified keybinds everywhere possible. Uses the [[https://github.com/emacs-evil/evil-collection][evil-collection]] plugin + as a foundation. + +** Packages +- [[doom-package:][evil]] +- [[doom-package:][evil-args]] +- [[doom-package:][evil-collection]] if [[doom-module:][+everywhere]] +- [[doom-package:][evil-easymotion]] +- [[doom-package:][evil-embrace]] +- [[doom-package:][evil-escape]] +- [[doom-package:][evil-exchange]] +- [[doom-package:][evil-indent-plus]] +- [[doom-package:][evil-lion]] +- [[doom-package:][evil-nerd-commentary]] +- [[doom-package:][evil-numbers]] +- [[doom-package:][evil-quick-diff]] +- [[doom-package:][evil-snipe]] +- [[doom-package:][evil-surround]] +- [[doom-package:][evil-textobj-anyblock]] +- [[doom-package:][evil-vimish-fold]] +- [[doom-package:][evil-visualstar]] +- [[doom-package:][exato]] ** Hacks -+ The o/O keys will respect and continue commented lines (can be disabled by +- The o/O keys will respect and continue commented lines (can be disabled by setting ~+evil-want-o/O-to-continue-comments~ to ~nil~). -+ In visual mode, =*= and =#= will search for the current selection instead of - the word-at-point. -+ The ~:g[lobal]~ ex command has been modified to highlight matches. -+ More of vim's filename modifiers are supported in ex commands (like ~:p~, +- In visual mode, [[kbd:][*]] and [[kbd:][#]] will search for the current selection instead of the + word-at-point. +- The ~:g[lobal]~ ex command has been modified to highlight matches. +- More of vim's filename modifiers are supported in ex commands (like ~:p~, ~:p:h~ or ~:t~) than vanilla evil-mode offers. -+ A custom filename modifier is available in Doom: ~:P~, which expands to the +- A custom filename modifier is available in Doom: ~:P~, which expands to the project root (throws an error if not in a project). -* Prerequisites -This module has no external prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** Ported vim plugins The following vim plugins have been ported to evil: -| Vim Plugin | Emacs Plugin | Keybind(s) | -|-----------------------+--------------------------------+--------------------------------------------| -| vim-commentary | evil-nerd-commenter | omap =gc= | -| vim-easymotion | evil-easymotion | omap =gs= | -| vim-lion | evil-lion | omap =gl= / =gL= | -| vim-seek or vim-sneak | evil-snipe | mmap =s= / =S=, omap =z= / =Z= & =x= / =X= | -| vim-surround | evil-embrace and evil-surround | vmap =S=, omap =ys= | -| vim-unimpaired | (provided by Doom) | [[https://github.com/hlissner/doom-emacs/blob/develop/modules/editor/evil/config.el#L413-L460][see the list]] | +| Vim Plugin | Emacs Plugin | Keybind(s) | +|-----------------------+--------------------------------+--------------------------------| +| vim-commentary | evil-nerd-commenter | omap [[kbd:][gc]] | +| vim-easymotion | evil-easymotion | omap [[kbd:][gs]] | +| vim-lion | evil-lion | omap [[kbd:][gl]] / [[kbd:][gL]] | +| vim-seek or vim-sneak | evil-snipe | mmap [[kbd:][s]] / [[kbd:][S]], omap [[kbd:][z]] / [[kbd:][Z]] & [[kbd:][x]] / [[kbd:][X]] | +| vim-surround | evil-embrace and evil-surround | vmap [[kbd:][S]], omap [[kbd:][ys]] | +| vim-unimpaired | (provided by Doom) | [[https://github.com/hlissner/doom-emacs/blob/develop/modules/editor/evil/config.el#L413-L460][see the list]] | This module has also ported vim-unimpaired keybinds to Emacs. In other modules: -+ The tools/neotree & tools/treemacs modules provide a =NERDTree= equivalent. -+ The editor/multiple-cursors module contains functionality equal to the +- The [[doom-module:][:ui neotree]] & [[doom-module:][:ui treemacs]] modules provide a =NERDTree= equivalent. +- The [[doom-module:][:editor multiple-cursors]] module contains functionality equal to the following vim plugins: - + evil-multiedit => vim-multiedit - + evil-mc => vim-multiple-cursors + - [[doom-package:][evil-multiedit]] => [[github:hlissner/vim-multiedit][vim-multiedit]] + - [[doom-package:][evil-mc]] => [[https://github.com/terryma/vim-multiple-cursors][vim-multiple-cursors]] ** Custom Text Objects This module provides a couple extra text objects, along with the built-in ones. For posterity, here are the built-in ones: -+ =w W= words -+ =s= sentences -+ =p= paragraphs -+ =b= parenthesized blocks -+ =b ( ) { } [ ] < >= braces, parentheses and brackets -+ =' " `= quotes -+ =t= tags -+ =o= symbols +- [[kbd:][w W]] words +- [[kbd:][s]] sentences +- [[kbd:][p]] paragraphs +- [[kbd:][b]] parenthesized blocks +- [[kbd:][b ( ) { } [ ] < >]] braces, parentheses and brackets +- [[kbd:][' " `]] quotes +- [[kbd:][t]] tags +- [[kbd:][o]] symbols And these are text objects added by this module: - -+ =a= C-style function arguments (provided by ~evil-args~) -+ =B= any block delimited by braces, parentheses or brackets (provided by +- [[kbd:][a]] C-style function arguments (provided by ~evil-args~) +- [[kbd:][B]] any block delimited by braces, parentheses or brackets (provided by ~evil-textobj-anyblock~) -+ =c= Comments -+ =f= For functions (but relies on the major mode to have sane definitions for +- [[kbd:][c]] Comments +- [[kbd:][f]] For functions (but relies on the major mode to have sane definitions for ~beginning-of-defun-function~ and ~end-of-defun-function~) -+ =g= The entire buffer -+ =i j k= by indentation (=k= includes one line above; =j= includes one line - above and below) (provided by ~evil-indent-plus~) -+ =q= For quotes (any kind) -+ =u= For URLs -+ =x= XML attributes (provided by ~exato~) +- [[kbd:][g]] The entire buffer +- [[kbd:][i j k]] by indentation ([[kbd:][k]] includes one line above; [[kbd:][j]] includes one line above and + below) (provided by ~evil-indent-plus~) +- [[kbd:][q]] For quotes (any kind) +- [[kbd:][u]] For URLs +- [[kbd:][x]] XML attributes (provided by ~exato~) ** Custom Ex Commands | Ex Command | Description | @@ -137,64 +137,92 @@ And these are text objects added by this module: | ~:rm[!] [PATH]~ | Delete the current buffer's file and buffer | | ~:tcd[!]~ | Send =cd X= to tmux. X = the project root if BANG, X = ~default-directory~ otherwise | -* Configuration -** Removing evil-mode -You must do two things to remove Evil: - -1. Remove =:editor evil= from =~/.doom.d/init.el=, -2. Run ~doom sync~ to clean up lingering dependencies and regenerate your - autoloads files. -3. [OPTIONAL] You may want to assign new values to ~doom-leader-alt-key~ and - ~doom-localleader-alt-key~. These are bound to =C-c= and =C-c l= by default. - +* TODO Configuration #+begin_quote -Ignore ~doom-leader-key~ and ~doom-localleader-key~, they don't apply to -non-evil sessions. + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] #+end_quote -Evil-specific configuration and keybindings (defined with ~map!~) will be -ignored without =:editor evil= present (and omitted when byte-compiling). +* Troubleshooting +[[doom-report:][Report an issue?]] -Keep in mind that, at the time of this writing, Doom was designed by a vimmer, -for vimmers. Little consideration has been put into designing a keybind scheme -for vanilla Emacs users (though it's being worked on!). +** Can't access the universal argument key ([[kbd:][C-u]]) +For maximum Vim emulation, this module commandeers the C-u key for scrolling (as +it does in Vim). The same goes for [[kbd:][C-u]] in insert mode (which deletes to BOL). In +both cases the universal argument has been moved to [[kbd:][ u]]. -That means that much of Doom's functionality will be orphaned in an evil-less -setup. You'll have to set your own keybinds. +To undo this, use: +#+begin_src emacs-lisp +;; add to $DOOMDIR/config.el +(setq! evil-want-C-u-scroll nil + evil-want-C-u-delete nil) +#+end_src -I suggest studying [[file:../../config/default/+emacs-bindings.el][config/default/+emacs-bindings.el]] to see what keybinds are -available for non-evil users. Otherwise, you may find inspiration [[file:../../../docs/example_configs.org][on the example -Doom configurations page]]. - -** Restoring old substitution behavior on s/S -Doom replaces the =s= and =S= keys with the =evil-snipe= package (a port of +** The [[kbd:][s]]/[[kbd:][S]] keys behave differently from Vim +Doom replaces the [[kbd:][s]] and [[kbd:][S]] keys with the [[doom-package:][evil-snipe]] package (a port of vim-seek/vim-sneak for 2-character versions of f/F/t/T). To disable evil-snipe on s/S, you can either: - 1. Disable ~evil-snipe-mode~ by adding ~(remove-hook 'doom-first-input-hook #'evil-snipe-mode)~ to =$DOOMDIR/config.el=, -2. Or disable =evil-snipe= completely with ~(package! evil-snipe :disable t)~ +2. Or disable [[doom-package:][evil-snipe]] completely with ~(package! evil-snipe :disable t)~ added to =$DOOMDIR/packages.el=, but this will also disable incremental highlighting for the f/F/t/T motions keys. -3. Or use =cl= and =cc=, respectively; they do the same thing. -** Restoring old Y behavior (yank the whole line) -Doom changes the behavior of the =Y= key in normal mode to yank-to-EOL -(equivalent to =y$=). This was to make it consistent with the =C= and =D= -capital operators, and because it was redundant with =yy=, which is easier to -type than =y$=. +3. Or use [[kbd:][cl]] and [[kbd:][cc]], respectively; they do the same thing. + +** The [[kbd:][Y]] key behaves differently from Vim (should yank the whole line) +Doom changes the behavior of the [[kbd:][Y]] key in normal mode to yank-to-EOL (equivalent +to [[kbd:][y$]]). This was to make it consistent with the [[kbd:][C]] and [[kbd:][D]] capital operators, and +because it was redundant with [[kbd:][yy]], which is easier to type than [[kbd:][y$]]. If you prefer the old behavior, it can be reversed with: - -#+BEGIN_SRC elisp -;; add to ~/.doom.d/config.el +#+begin_src emacs-lisp +;; add to $DOOMDIR/config.el (setq! evil-want-Y-yank-to-eol nil) -#+END_SRC -** Disabling cursor movement when exiting insert mode -Vim (and evil) move the cursor one character back when exiting insert mode. If -you prefer that it didn't, set: +#+end_src -#+BEGIN_SRC elisp -;; add to ~/.doom.d/config.el -(setq evil-move-cursor-back nil) -#+END_SRC +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +** How do I remove evil? +:PROPERTIES: +:ID: f3925da6-5f0b-4d11-aa08-7bb58bea1982 +:END: +1. [[id:01cffea4-3329-45e2-a892-95a384ab2338][Disable this module]]. +2. Run ~$ doom sync~ to clean up lingering dependencies and regenerate your + autoloads files. +3. [OPTIONAL] Change ~doom-leader-alt-key~ and ~doom-localleader-alt-key~. These + are bound to [[kbd:][C-c]] and [[kbd:][C-c l]] by default. + +#+begin_quote + 🚧 Ignore ~doom-leader-key~ and ~doom-localleader-key~, they don't apply to + non-evil sessions. +#+end_quote + +Evil-specific configuration and keybindings (defined with ~map!~) will be +ignored without [[doom-module:][:editor evil]] present (and omitted when byte-compiling). + +** Include underscores in evil word motions? +A more in-depth answer and explanation for this can be found [[https://evil.readthedocs.io/en/latest/faq.html#underscore-is-not-a-word-character][in Evil's +documentation]]. + +TL;DR If you want the underscore to be recognized as word character, you can +modify its entry in the syntax-table: +#+begin_src emacs-lisp +(modify-syntax-entry ?_ "w") +#+end_src + +This gives the underscore the word syntax-class. You can use a mode-hook to +modify the syntax-table in all buffers of some mode, e.g. +#+begin_src emacs-lisp +;; For python +(add-hook! 'python-mode-hook (modify-syntax-entry ?_ "w")) +;; For ruby +(add-hook! 'ruby-mode-hook (modify-syntax-entry ?_ "w")) +;; For Javascript +(add-hook! 'js2-mode-hook (modify-syntax-entry ?_ "w")) +#+end_src + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/file-templates/README.org b/modules/editor/file-templates/README.org index 9a195f6e5..29c0ca3e1 100644 --- a/modules/editor/file-templates/README.org +++ b/modules/editor/file-templates/README.org @@ -1,83 +1,97 @@ -#+TITLE: editor/file-templates -#+DATE: February 11, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :editor file-templates +#+subtitle: Fill the void in your empty files +#+created: February 11, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_2:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#usage][Usage]] - - [[#inserting-oss-licenses][Inserting OSS licenses]] -- [[#configuration][Configuration]] - - [[#registering-a-new-file-template][Registering a new file template]] - - [[#changing-existing-file-templates][Changing existing file templates]] - - [[#adding-new-oss-licenses][Adding new OSS licenses]] -- [[#troubleshooting][Troubleshooting]] -- [[#appendix][Appendix]] - - [[#api][API]] - - [[#commands][Commands]] - - [[#variables][Variables]] +* Description :unfold: +This module adds file templates for blank files, powered by [[doom-package:][yasnippet]]. -* Description -This module adds file templates for blank files, powered by yasnippet. +** Maintainers +- [[doom-user:][@hlissner]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -This module installs no plugins. +** Module flags +/This module has no flags./ -* Prerequisites -This module has no prerequisites. +** Packages +/This module doesn't install any packages./ -* Usage -File templates are automatically expanded when opening empty files. +** Hacks +- [[doom-package:][yasnippet]] -They are also regular yasnippet snippets, which can be expanded by typing their -trigger and pressing =TAB=. By convention, the triggers for file templates are -prefixed with two underscores ~__~. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +File templates are automatically expanded when opening empty files who match one +of the rules in the ~+file-templates-alist~ variable. + +These templates are simply yasnippet snippets, which can also be expanded by +typing their trigger and pressing [[kbd:][TAB]]. By convention, the triggers for file +templates are prefixed with two underscores ~__~ (the trigger for the default +file template of a major mode is almost always ~__~). ** Inserting OSS licenses A special command is available for inserting software licenses: ~M-x +file-templates/insert-license~. #+begin_quote -Licenses with a ~-bp~ suffix are boilerplate templates; shorter versions meant -for comment headers in code. + πŸ“Œ Licenses with a ~-bp~ suffix are boilerplate templates; i.e. shorter + versions intended for comment headers in code files. #+end_quote -* Configuration -** Registering a new file template -Look into the documentation of ~set-file-template!~ and ~set-file-templates!~. -** Changing existing file templates -Simply register a new template (using ~set-file-template!~) that matches the same -file. The new template would be pushed to the top of ~+file-template-alist~ and -thus would take priority while searching for a template to insert. -** Adding new OSS licenses -The ~+file-templates/insert-license~ command searches for snippets under -~text-mode~ that are named ~__license-ABC~, where ABC is the short name of the -license. e.g. ~__license-mit~. +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -So long as these files exist, ~+file-templates/insert-license~ will recognize -them. +** Adding new or changing existing file templates +New file templates can be added to +=$DOOMDIR/snippets/{major-mode}/{snippet-name}=. The yasnippet documentation +covers [[https://joaotavora.github.io/yasnippet/snippet-development.html][how to write a snippet]]. You can map a snippet to a file path, major mode, +or another arbitrary predicate using [[fn:][set-file-template!]]. + +Look into its documentation with [[kbd:][ f set-file-template\!]]. + +** Adding new OSS licenses +Add snippet files to =$DOOMDIR/snippets/text-mode/= with the =__licenses-= +prefix and [[fn:][+file-templates/insert-license]] will recognize them. E.g. +=$DOOMDIR/snippets/text-mode/__license-mit=. * Troubleshooting -If a file template isn't expanding where you expect it to, run ~M-x -+file-templates/debug~. This will report to you what file template rule would -apply for the correct file. +- If a file template isn't expanding where you expect it to, run ~M-x + +file-templates/debug~. This will report to you what file template rule would + apply for the correct file. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]] +#+end_quote -* Appendix ** API -+ ~set-file-template! PRED &rest PLIST~ -+ ~set-file-templates! &rest TEMPLATES~ +- ~set-file-template! PRED &rest PLIST~ +- ~set-file-templates! &rest TEMPLATES~ ** Commands -+ ~+file-templates/insert-license~ -+ ~+file-templates/debug~ +- ~+file-templates/insert-license~ +- ~+file-templates/debug~ ** Variables -+ ~+file-templates-dir~ -+ ~+file-templates-default-trigger~ -+ ~+file-templates-alist~ +- ~+file-templates-dir~ +- ~+file-templates-default-trigger~ +- ~+file-templates-alist~ diff --git a/modules/editor/file-templates/autoload.el b/modules/editor/file-templates/autoload.el index 114507cae..c96d79beb 100644 --- a/modules/editor/file-templates/autoload.el +++ b/modules/editor/file-templates/autoload.el @@ -96,6 +96,14 @@ evil is loaded and enabled)." (file-relative-name path doom-private-dir)) ((abbreviate-file-name path)))))) +;;;###autoload +(defun +file-templates-module-for-path (&optional path) + "Generate a title for a doom module's readme at PATH." + (let ((m (doom-module-from-path (or path (buffer-file-name))))) + (if (eq (cdr m) 'README.org) + (symbol-name (car m)) + (format "%s %s" (car m) (cdr m))))) + ;; ;;; Commands @@ -133,3 +141,20 @@ for it. This is used for testing." :key #'yas--template-key :test #'equal)) (message "Found %s" (cons pred plist)) (message "Found rule, but can't find associated snippet: %s" (cons pred plist))))) + + +;; +;;; Trigger functions + +(defun +file-templates-insert-doom-docs-fn () + "Expand one of Doom's README templates depending." + (+file-templates--expand + t :trigger + (let ((path (file-truename (buffer-file-name)))) + (cond ((string-match-p "/modules/[^/]+/README\\.org$" path) + "__doom-category-readme") + ((string-match-p "/modules/[^/]+/[^/]+/README\\.org$" path) + "__doom-readme") + ((file-in-directory-p path doom-docs-dir) + "__doom-docs") + ("__"))))) diff --git a/modules/editor/file-templates/config.el b/modules/editor/file-templates/config.el index 27e580e89..379edcfce 100644 --- a/modules/editor/file-templates/config.el +++ b/modules/editor/file-templates/config.el @@ -71,9 +71,8 @@ don't have a :trigger property in `+file-templates-alist'.") ("/shell\\.nix$" :trigger "__shell.nix") (nix-mode) ;; Org - ("/README\\.org$" - :when +file-templates-in-emacs-dirs-p - :trigger "__doom-readme" + (doom-docs-org-mode + :trigger +file-templates-insert-doom-docs-fn :mode org-mode) (org-journal-mode :ignore t) (org-mode) diff --git a/modules/editor/file-templates/templates/org-mode/__doom-category-readme b/modules/editor/file-templates/templates/org-mode/__doom-category-readme new file mode 100644 index 000000000..570651045 --- /dev/null +++ b/modules/editor/file-templates/templates/org-mode/__doom-category-readme @@ -0,0 +1,10 @@ +# -*- mode: snippet -*- +# name: Doom category readme +# -- +#+title: `(+file-templates-module-for-path)` +#+created: `(format-time-string "%B %d, %Y")` +#+since: `(car (split-string doom-version "-"))` +$0 +* Description +Replace this with a description of what modules in this category are for, +including any important information (like load order constraints). \ No newline at end of file diff --git a/modules/editor/file-templates/templates/org-mode/__doom-docs b/modules/editor/file-templates/templates/org-mode/__doom-docs new file mode 100644 index 000000000..b1fefa52c --- /dev/null +++ b/modules/editor/file-templates/templates/org-mode/__doom-docs @@ -0,0 +1,7 @@ +# -*- mode: snippet -*- +# name: Doom documentation +# -- +#+title: ${1:Title} +#+subtitle: ${2:Subtitle} + +$0 \ No newline at end of file diff --git a/modules/editor/file-templates/templates/org-mode/__doom-readme b/modules/editor/file-templates/templates/org-mode/__doom-readme index 695067459..10c49ef26 100644 --- a/modules/editor/file-templates/templates/org-mode/__doom-readme +++ b/modules/editor/file-templates/templates/org-mode/__doom-readme @@ -1,70 +1,194 @@ # -*- mode: snippet -*- # name: Doom module readme # -- -#+TITLE: ${1:`(if (string-match "modules/\\([^/]+\\)/\\([^/]+\\)/.+" buffer-file-name) - (format "%s/%s" - (match-string 1 buffer-file-name) - (match-string 2 buffer-file-name)) - "")`} -#+DATE: `(format (format-time-string "%B %%s, %Y") (string-to-number (format-time-string "%d")))` -#+SINCE: ${2:} -#+STARTUP: inlineimages nofold +#+title: `(+file-templates-module-for-path)` +#+subtitle: +#+created: `(format-time-string "%B %d, %Y")` +#+since: `(car (split-string doom-version "-"))` (#COMMIT-OR-PR-REF) -* Table of Contents :TOC_3:noexport: +* Description :unfold: +$0Replace this with a short (1-2 sentence) description of what this module does. +This is displayed in the module index. -* Description -${3:# A summary of what this module does.} - -+ If possible, include a brief list of feature highlights here -+ Like code completion, syntax checking or available snippets -+ Include links to packages & external things where possible +Then a longer, multiple paragraph description goes here, which should explain +the purpose of the module and the features/technology(ies) it provides. ** Maintainers -+ @username_linked_to_gihub (Author) -+ @username_linked_to_gihub -+ @username_linked_to_gihub +- [[doom-user:][@github_username]] +- [[doom-user:][@github_username]] +- [[doom-user:][@github_username]] -# If this module has no maintainers, then... -This module has no dedicated maintainers. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+flag1= A short description of what this flag does and what it might need - when enabled. -+ =+flag2= A short description of what this flag does and what it might need - when enabled. -+ =+flag3= A short description of what this flag does and what it might need - when enabled. +# If a module has no maintainers and can't be casually maintained by Henrik +# alone, use: +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +# Otherwise, use: +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +# Flags should be in alphanumerical order. +- +bar :: + A short description of what this flag does and what it might need when + enabled. +- +childframe :: + Display X in a [[https://www.gnu.org/software/emacs/manual/html_node/elisp/Child-Frames.html][child frame]] rather than an overlay or tooltip. *Requires GUI + Emacs.* +- +lsp :: + Enable LSP support for ~X-mode~. Requires [[doom-module:][:tools lsp]] and a + langserver (supports A, B, and C). # If this module has no flags, then... -This module provides no flags. +/This module has no flags./ -** Plugins -# A list of linked plugins -+ [[https://orgmode.org/][org-plus-contrib]] -+ [[https://github.com/sabof/org-bullets][org-bullets]] -+ [[https://github.com/TobiasZawada/org-yt][org-yt]] -+ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=) -+ =:lang crystal= - + [[https://github.com/brantou/ob-crystal][ob-crystal]] -+ =:lang go= - + [[https://github.com/pope/ob-go][ob-go]] -+ =+present= - + [[https://github.com/anler/centered-window-mode][centered-window]] - + [[https://github.com/takaxp/org-tree-slide][org-tree-slide]] - + [[https://gitlab.com/oer/org-re-reveal][org-re-reveal]] +# If this module has flags but you can't document them now, add a TODO to the +# heading and use: +#+begin_quote + πŸ”¨ This module has flags, but they aren't documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** Packages +- [[doom-package:][org]] +- [[doom-package:][org-contrib]] if [[doom-module:][+contrib]] +- [[doom-package:][org-bullets]] unless [[doom-module:][+bullets]] +- if [[doom-module:][+present]] + - [[doom-package:][centered-window]] + - [[doom-package:][org-tree-slide]] + - [[doom-package:][org-re-reveal]] + +# If this module installs no packages, then... +/This module doesn't install any packages./ + +# If this module installs packages, but you can't document them now, add a TODO +# to the heading and use: +#+begin_quote + πŸ”¨ This module installs packages, but they aren't documented yet. [[doom-contrib-module:][Document + them?]] +#+end_quote ** Hacks -# A list of internal modifications to included packages; omit if unneeded +# Place a list of internal (and potentially unexpected) modifications to +# included packages: +- Fixed X which should help you do Y +- Advised Z to work harder, better, faster, stronger. +- Tricked the hobbitses into giving me the precious. -* Prerequisites -This module has no prerequisites. +# If there aren't any hacks, use: +/No hacks documented for this module./ -* Features -# An in-depth list of features, how to use them, and their dependencies. +# If this module contains hacks, but you can't document them now, add a TODO to +# the heading and use: +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote -* Configuration -# How to configure this module, including common problems and how to address them. +** TODO Changelog +# Do not edit this by hand. Your commits are your changelog. Commits that +# shouldn't show up should use the 'Amend: ...' trailer (see +# https://docs.doomemacs.org/-/git-conventions for details). +# +# ALSO: Version headings should be linked to the respective heading in +# docs/changelog.org. +** [[doom-tag:][v21.12.0]] [2021-12-30] +*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]] +commit BODY +*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]] +commit BODY +*** [[doom-ref:a1b2c3d4][commit SUBJECT linked to github commit]] +commit BODY + +# If no changelog is available, use: +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +# This section should describe, in-depth, how to set up this module and its +# dependencies, starting with this line: +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] +# ...Then list its external requirements, if any. +This module requires: +- ... +- ... +- ... +# And finally, go into detail about how to install them. + +# If there are no external requirements, use: +/This module has no external requirements./ + +# If there are prerequisites but you can't document them yet, add TODO to the +# heading and use: +#+begin_quote + πŸ”¨ /No installation steps have been documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* Usage +# Walk the user through how this module is used. + +# If this is left empty, add TODO to the heading and use: +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +# If this section has incomplete content, add TODO to the heading and use: +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +* TODO Configuration +# Walk the user through how to configure this module, including any variables it +# exposes or user-facing configuration API. + +# If this is left empty, add TODO to the heading and use: +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +# If this section has incomplete content, add TODO to the heading and use: +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote * Troubleshooting -# Common issues and their solution, or places to look for help. -$0 \ No newline at end of file +# List common issues and any workarounds/solutions, or link to external resources. +[[doom-report:][Report an issue?]] + +** Common issue +Solution. +** Common issue +Solution. +** Common issue +Solution. + +# If this is left empty, use: +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +[[doom-suggest-faq:][Ask a question?]] + +# This is for adoption, design, or niche questions. More general +# usage/configuration matters should be covered in the sections above. +** Question +Answer +** Question +Answer +** Question +Answer + +# If no questions are available, use +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +# A glossary of important major modes, minor modes, commands, functions, faces, +# and variables that this module exposes. It doesn't have to be exhaustive and +# should omit explanation/documentation. + +# If this is left empty, add TODO to the heading and use: +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote + +# If this section has incomplete content, add TODO to the heading and use: +#+begin_quote + πŸ”¨ /This module's appendix is incomplete./ [[doom-contrib-module:][Write more?]] +#+end_quote \ No newline at end of file diff --git a/modules/editor/fold/README.org b/modules/editor/fold/README.org index 5064eb72a..80592ae96 100644 --- a/modules/editor/fold/README.org +++ b/modules/editor/fold/README.org @@ -1,44 +1,70 @@ -#+TITLE: editor/fold -#+DATE: February 17, 2019 -#+SINCE: v2.1 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :editor fold +#+subtitle: What you can't see won't hurt you +#+created: May 15, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This module marries hideshow, vimish-fold and outline-minor-mode to bring you +* Description :unfold: +This module marries [[doom-package:][hideshow]], [[doom-package:][vimish-fold]], and ~outline-minor-mode~ to bring you marker, indent and syntax-based code folding for as many languages as possible. -** Module Flags -This module provides no flags. +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ [[https://github.com/alexmurray/evil-vimish-fold][evil-vimish-fold]] -+ [[https://github.com/matsievskiysv/vimish-fold][vimish-fold]] +[[doom-contrib-maintainer:][Become a maintainer?]] -* Prerequisites -This module has no prerequisites. +** Module flags +/This module has no flags./ -* Features +** Packages +- [[doom-package:][evil-vimish-fold]] +- [[doom-package:][vimish-fold]] +- if [[doom-module:][:tools tree-sitter]] + - [[doom-package:][ts-fold]] -Emacs keybinds when evil +everywhere is disabled. -| Keybind | Description | -|------------------------+---------------------------| -| =C-c C-f C-f= | Fold region | -| =C-c C-f C-u= or =C `= | Unfold region | -| =C-c C-f C-d= | Delete folded region | -| =C-c C-f C-a C-f= | Fold all regions | -| =C-c C-f C-a C-u= | Unfold all regions | -| =C-c C-a C-d= | Delete all folded regions | +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +Emacs keybinds when [[doom-module:][:editor evil +everywhere]] is disabled: +| Keybind | Description | +|--------------------+---------------------------| +| [[kbd:][C-c C-f C-f]] | Fold region | +| [[kbd:][C-c C-f C-u]] or [[kbd:][C `]] | Unfold region | +| [[kbd:][C-c C-f C-d]] | Delete folded region | +| [[kbd:][C-c C-f C-a C-f]] | Fold all regions | +| [[kbd:][C-c C-f C-a C-u]] | Unfold all regions | +| [[kbd:][C-c C-a C-d]] | Delete all folded regions | * TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -Sometimes an unfolded region does not fold back with =C-c C-f C-f=. To bypass this bug you must delete the folded region (=C-c C-f C-d=) and then fold it(=C-c C-f C-f=) again. +- Sometimes, an unfolded region won't fold back with [[kbd:][C-c C-f C-f]]. To bypass this + bug you must delete the folded region ([[kbd:][C-c C-f C-d]]) and then fold it ([[kbd:][C-c C-f + C-f]]) again. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/format/README.org b/modules/editor/format/README.org index 95569c4a9..30ae62faf 100644 --- a/modules/editor/format/README.org +++ b/modules/editor/format/README.org @@ -1,30 +1,16 @@ -#+TITLE: editor/format -#+DATE: July 25, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :editor format +#+subtitle: Standardize your ugly code +#+created: July 26, 2020 +#+since: 21.12.0 #+begin_quote -This module has been scheduled for a rewrite. Its documentation will remain -incomplete and edge cases left unpatched in the meantime. A preview of this -rewrite can be found [[https://github.com/hlissner/doom-emacs-private/tree/master/modules/editor/format][in my private config]]. + πŸ”¨ This module has been scheduled for a rewrite. Its documentation will remain + incomplete and edge cases left unpatched in the meantime. A preview of this + rewrite can be found [[https://github.com/hlissner/doom-emacs-private/tree/master/modules/editor/format][in my private config]]. #+end_quote -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#automatic-reformatting-when-saving-buffers][Automatic reformatting when saving buffers]] - - [[#disabling-the-lsp-formatter][Disabling the LSP formatter]] - - [[#defining-your-own-formatters][Defining your own formatters]] - - [[#selecting-a-specific-formatter-for-a-particular-buffer][Selecting a specific formatter for a particular buffer]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module integrates code formatters into Emacs. Here are some of the formatters that it currently supports: @@ -37,88 +23,102 @@ rustfmt, scalafmt, script shfmt, snakefmt, sqlformat, styler, swiftformat, tidy #+end_quote ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+onsave= Preform buffer-wide reformatting of a buffer when you save it. See - ~+format-on-save-enabled-modes~ to control what major modes to (or not to) +** Module flags +- +onsave :: + Enable reformatting of a buffer when it is saved. See + [[var:][+format-on-save-enabled-modes]] to control what major modes to (or not to) format on save. -** Plugins -+ [[https://github.com/lassik/emacs-format-all-the-code][format-all]] +** Packages +- [[doom-package:][format-all]] ** Hacks -+ format-all has been heavily modified to suit Doom's goals for this module: - + Reformatted text is applied to the buffer by RCS patch, as to reduce its +- format-all has been heavily modified to suit Doom's goals for this module: + - Reformatted text is applied to the buffer by RCS patch, as to reduce its affect on cursor position. - + Adds partial formatting, i.e. you can now reformat a subset of the buffer. - + Adds the ability to use any arbitrary formatter on the current buffer if you - pass the universal argument to ~+format/buffer~ or ~+format/region~ (i.e. + - Adds partial formatting, i.e. you can now reformat a subset of the buffer. + - Adds the ability to use any arbitrary formatter on the current buffer if you + pass the universal argument to [[fn:][+format/buffer]] or [[fn:][+format/region]] (i.e. removes the major-mode lock on formatters). -* Prerequisites -This module depends on external programs to perform the actual formatting. These -will need to be installed for them to work. In their absence, =format-all= will -fail silently. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -+ Angular/Vue (prettier) -+ Assembly (asmfmt) -+ Bazel Starlark (buildifier) -+ BibTeX (emacs) -+ C/C++/Objective-C (clang-format) -+ Cabal (cabal-fmt) -+ Clojure/ClojureScript (node-cljfmt) -+ CMake (cmake-format) -+ Crystal (crystal tool format) -+ CSS/Less/SCSS (prettier) -+ D (dfmt) -+ Dart (dartfmt) -+ Dhall (dhall format) -+ Dockerfile (dockfmt) -+ Elixir (mix format) -+ Elm (elm-format) -+ Emacs Lisp (emacs) -+ Fish Shell (fish_indent) -+ Fortran 90 (fprettify) -+ Gleam (gleam format) -+ Go (gofmt) -+ GraphQL (prettier) -+ Haskell (brittany) -+ HTML/XHTML/XML (tidy) -+ Java (clang-format) -+ JavaScript/JSON/JSX (prettier) -+ Jsonnet (jsonnetfmt) -+ Kotlin (ktlint) -+ LaTeX (latexindent) -+ Ledger (ledger-mode) -+ Lua (lua-fmt) -+ Markdown (prettier) -+ Nix (nixfmt) -+ OCaml (ocp-indent) -+ Perl (perltidy) -+ PHP (prettier plugin-php) -+ Protocol Buffers (clang-format) -+ PureScript (purty) -+ Python (black) -+ R (styler) -+ Ruby (rufo) -+ Rust (rustfmt) -+ Scala (scalafmt) -+ Shell script (shfmt) -+ Snakemake (snakefmt) -+ Solidity (prettier-plugin-solidity) -+ SQL (sqlformat) -+ Swift (swiftformat) -+ Terraform (terraform fmt) -+ TOML (prettier-plugin-toml) -+ TypeScript/TSX (prettier) -+ Verilog (iStyle) -+ YAML (prettier) +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +This module has no direct requirements, but each language will need one of their +supported formatter programs in order for this to work. In their absence, +[[doom-package:][format-all]] will fail silently. + +Supported formatters: +- Angular/Vue (prettier) +- Assembly (asmfmt) +- Bazel Starlark (buildifier) +- BibTeX (emacs) +- C/C++/Objective-C (clang-format) +- Cabal (cabal-fmt) +- Clojure/ClojureScript (node-cljfmt) +- CMake (cmake-format) +- Crystal (crystal tool format) +- CSS/Less/SCSS (prettier) +- D (dfmt) +- Dart (dartfmt) +- Dhall (dhall format) +- Dockerfile (dockfmt) +- Elixir (mix format) +- Elm (elm-format) +- Emacs Lisp (emacs) +- Fish Shell (fish_indent) +- Fortran 90 (fprettify) +- Gleam (gleam format) +- Go (gofmt) +- GraphQL (prettier) +- Haskell (brittany) +- HTML/XHTML/XML (tidy) +- Java (clang-format) +- JavaScript/JSON/JSX (prettier) +- Jsonnet (jsonnetfmt) +- Kotlin (ktlint) +- LaTeX (latexindent) +- Ledger (ledger-mode) +- Lua (lua-fmt) +- Markdown (prettier) +- Nix (nixfmt) +- OCaml (ocp-indent) +- Perl (perltidy) +- PHP (prettier plugin-php) +- Protocol Buffers (clang-format) +- PureScript (purty) +- Python (black) +- R (styler) +- Ruby (rufo) +- Rust (rustfmt) +- Scala (scalafmt) +- Shell script (shfmt) +- Snakemake (snakefmt) +- Solidity (prettier-plugin-solidity) +- SQL (sqlformat) +- Swift (swiftformat) +- Terraform (terraform fmt) +- TOML (prettier-plugin-toml) +- TypeScript/TSX (prettier) +- Verilog (iStyle) +- YAML (prettier) + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Automatic reformatting when saving buffers There are two ways to achieve this. Either through the =+onsave= flag, or by adding ~format-all-mode~ to the hook of each major mode you want this behavior @@ -128,29 +128,29 @@ If you choose the former, what modes it applies to can be changed by modifying ~+format-on-save-enabled-modes~, which contains a list of major modes. If the first item in the list is the symbol ~not~, the list is negated. This is its default value: -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (setq +format-on-save-enabled-modes '(not emacs-lisp-mode ; elisp's mechanisms are good enough sql-mode ; sqlformat is currently broken tex-mode ; latexindent is broken latex-mode)) -#+END_SRC +#+end_src If you want to format code when you save a buffer, but want more granular control over which major modes this behavior is enabled in, there is an -alternative. Make sure =+onsave= is disabled before you try this: - -#+BEGIN_SRC elisp +alternative. Make sure [[doom-module:][+onsave]] is disabled before you try this: +#+begin_src emacs-lisp (add-hook 'python-mode-hook #'format-all-mode) (add-hook 'js2-mode-hook #'format-all-mode) -#+END_SRC +#+end_src ** Disabling the LSP formatter If you are in a buffer with ~lsp-mode~ enabled and a server that supports -=textDocument/formatting=, it will be used instead of =format-all='s formatter. +=textDocument/formatting=, it will be used instead of [[doom-package:][format-all]]'s formatter. + To disable this behavior universally use: ~(setq +format-with-lsp nil)~ -+ To disable this behavior in one mode: ~(setq-hook! 'python-mode-hook +format-with-lsp nil)~ ++ To disable this behavior in one mode: ~(setq-hook! 'python-mode-hook + +format-with-lsp nil)~ ** TODO Defining your own formatters See the ~set-formatter!~ function. @@ -158,17 +158,24 @@ See the ~set-formatter!~ function. ** TODO Selecting a specific formatter for a particular buffer Set the buffer-local variable ~+format-with~ to the name of the formatter to use. e.g. - -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (setq-hook! 'python-mode-hook +format-with 'html-tidy) ;; Or set it to `:none' to disable formatting (setq-hook! 'python-mode-hook +format-with :none) -#+END_SRC +#+end_src Formatters are referred to by the name they were defined with. They can be looked up in the ~format-all-mode-table~ hash table or in format-all's [[https://github.com/lassik/emacs-format-all-the-code/blob/master/format-all.el#L512][source code]]. * Troubleshooting -# Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/god/README.org b/modules/editor/god/README.org new file mode 100644 index 000000000..a0637a4dd --- /dev/null +++ b/modules/editor/god/README.org @@ -0,0 +1,56 @@ +# -*- mode: doom-docs-org -*- +#+title: :editor god +#+subtitle: IDDQD +#+created: October 13, 2021 +#+since: 21.12.0 + +#+begin_quote + 🚧 *This module is deprecated.* ~god-mode~ is EOL and no longer maintained. +#+end_quote + +* Description :unfold: +Adds [[doom-package:][god-mode]] support to Doom Emacs, allowing for entering commands without +modifier keys, similar to Vim's modality, separating command mode and insert +mode. + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][god-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/lispy/README.org b/modules/editor/lispy/README.org index 7deebcd1d..33e669c07 100644 --- a/modules/editor/lispy/README.org +++ b/modules/editor/lispy/README.org @@ -1,18 +1,13 @@ -#+TITLE: editor/lispy -#+DATE: October 27, 2018 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :editor lispy +#+subtitle: Vim for lisp, for people who don't like vim +#+created: October 27, 2018 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] -- [[#prerequisites][Prerequisites]] -- [[#troubleshooting][Troubleshooting]] - - [[#mouse-wheel-and-wrapadditional-wrap-key-themes-in-tty-emacs-2573][Mouse wheel and =wrap=/=additional-wrap= key themes in TTY Emacs (#2573)]] - -* Description -This module adds [[https://github.com/noctuid/lispyville][lispy]] key functionality in Lisp languages. - -This includes: +* Description :unfold: +This module adds a keybind scheme for navigating and editing S-expressions in +Lisps; including S-exp awareness for Evil users. This affects the following +languages: - Common Lisp - Emacs Lisp @@ -23,12 +18,43 @@ This includes: - Clojure - [[https://fennel-lang.org][Fennel]] -If evil is enabled, lispyville would also be activated for every mode where -lispy is active +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][lispy]] +- [[doom-package:][lispyville]] if [[doom-module:][:editor evil +everywhere]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +If [[doom-module:][:editor evil]] is enabled, [[doom-package:][lispyville]] would also be activated for every mode +where [[doom-package:][lispy]] is active. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote The default key themes that are set are as follows: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp '((operators normal) c-w (prettify insert) @@ -36,18 +62,25 @@ The default key themes that are set are as follows: slurp/barf-lispy additional additional-insert) -#+END_SRC +#+end_src To change the key themes set ~lispyville-key-theme~. Think of ~lispyville-key-theme~ as the equivalent of ~parinfer-extensions~. See lispyville's [[https://github.com/noctuid/lispyville/blob/master/README.org][README]] for more info on the specific keybindings of each key theme (starting [[https://github.com/noctuid/lispyville#operators-key-theme][here]]). -* Prerequisites -This module has no prerequisites. - * Troubleshooting +[[doom-report:][Report an issue?]] + ** Mouse wheel and =wrap=/=additional-wrap= key themes in TTY Emacs ([[https://github.com/hlissner/doom-emacs/issues/2573][#2573]]) -lispyville binds =M-[= to ~lispyville-wrap-brackets~ when the =wrap= or -=additional-wrap= key theme are enabled. In terminal Emacs, this is the key +lispyville binds [[kbd:][M-[]] to ~lispyville-wrap-brackets~ when the =wrap= or +=additional-wrap= key themes are enabled. In terminal Emacs, this is the key Emacs receives when you scroll with your mouse wheel. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/multiple-cursors/README.org b/modules/editor/multiple-cursors/README.org new file mode 100644 index 000000000..d5caa4263 --- /dev/null +++ b/modules/editor/multiple-cursors/README.org @@ -0,0 +1,79 @@ +# -*- mode: doom-docs-org -*- +#+title: :editor multiple-cursors +#+subtitle: Make all your mistakes at once +#+created: October 13, 2021 +#+since: 21.12.0 + +* Description :unfold: +This module adds a multiple cursors implementation to Emacs (two, if you use +evil) that loosely take after multi-cursors in Atom or Sublime Text. + +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- if [[doom-module:][:editor evil]] + - [[doom-package:][evil-multiedit]] + - [[doom-package:][evil-mc]] +- else + - [[doom-package:][multiple-cursors]] + +** Hacks +- Attempts to smooth over [[doom-package:][multiple-cursors]]' incompatibilities with [[doom-package:][evil]], which + is used internally in some third party plugins. +- Attempts to smooth over [[doom-package:][evil-mc]]'s incompatibilities with other packages, like + [[doom-package:][lispy]]. + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +** evil-mc +- The [[doom-package:][evil-mc]] keys are under the [[kbd:][gz]] prefix, e.g. + - [[kbd:][gzz]] to toggle new (frozen) cursors at point. + - [[kbd:][gzt]] to toggle mirroring on and off (or switch to insert mode to activate + them). + - [[kbd:][gzA]] to place cursors at the end of each selected line. + - [[kbd:][gzI]] will place them at the beginning. +- There's also the ex command ~:mc/REGEXP/FLAGS~, for laying down cursors by + regex. + +** evil-multiedit +Designates "interactive edit" regions. Only the textual changes to them are mirrored. + +- [[kbd:][M-d]] to iedit the symbol at point. Again to iedit its next match. +- [[kbd:][M-S-d]] to do it backwards. +- [[kbd:][R]] (in visual mode) to iedit all matches of the selection at point in the + buffer. +- Or ~:iedit/REGEX~ to iedit all matches of REGEX. + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/objed/README.org b/modules/editor/objed/README.org index 3b7af3de9..9f7ad247b 100644 --- a/modules/editor/objed/README.org +++ b/modules/editor/objed/README.org @@ -1,23 +1,61 @@ -#+TITLE: editor/objed -#+DATE: May 30, 2019 -#+SINCE: v2.1 +# -*- mode: doom-docs-org -*- +#+title: :editor objed +#+subtitle: Text object editing for the innocent +#+created: May 30, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - -* Description -This modules adds [[https://github.com/clemera/objed][objed]], a global minor-mode for navigating and manipulating -text objects. It combines the ideas of versor-mode and other editors like Vim or -Kakoune and tries to align them with regular Emacs conventions. - -#+begin_quote -This module is incompatible with the =:editor evil=. Enabling them both will -cause errors. -#+end_quote +* Description :unfold: +This modules adds [[doom-package:][objed]], a global minor-mode for navigating and manipulating +text objects. It combines the ideas of ~versor-mode~ and other editors like Vim +or Kakoune and tries to align them with regular Emacs conventions. [[https://github.com/clemera/objed][See the objed project README]] for information on keybinds and usage. -** Module Flags -+ ~+manual~ Do not turn =objed= automatically. The user is responsible for calling - `objed-activate` (bound to `M-SPC` if using the default Emacs bindings.) +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +manual :: + Don't activate [[doom-package:][objed]] at startup, automatically, leaving it to the user to call + [[fn:][objed-activate]] (bound to [[kbd:][M-SPC]] if using [[doom-module:][:config default +bindings]]). + +** Packages +- [[doom-package:][objed]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +#+begin_quote + 🚧 This module is incompatible with [[doom-module:][:editor evil]]. Do not enable them both at + the same time or you will get errors. +#+end_quote + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/parinfer/README.org b/modules/editor/parinfer/README.org index 210c8707b..87c51bd4c 100644 --- a/modules/editor/parinfer/README.org +++ b/modules/editor/parinfer/README.org @@ -1,55 +1,58 @@ -#+TITLE: editor/parinfer -#+DATE: June 9, 2018 -#+SINCE: v2.1 -#+STARTUP: inlineimages nofold - -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#keybindings][Keybindings]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +# -*- mode: doom-docs-org -*- +#+title: :editor parinfer +#+subtitle: For lispers that like Python more (i.e. nobody) +#+created: February 27, 2021 +#+since: 21.12.0 +* Description :unfold: Parinfer is a minor mode that aids the writing of Lisp code. It automatically infers parenthesis matching and indentation alignment, keeping your code balanced and beautiful. -Note that the original =parinfer-mode= has been deprecated and superceded by -=parinfer-rust-mode=, which has much better performance. - ** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -This module has no dedicated maintainers. +** Module flags +/This module has no flags./ -** Module Flags +** Packages +- [[doom-package:][parinfer-rust-mode]] -This module provides no flags. +** Hacks +/No hacks documented for this module./ -** Plugins +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -+ [[https://github.com/justinbarclay/parinfer-rust-mode][parinfer-rust-mode]] +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites +This module requires [[https://github.com/justinbarclay/parinfer-rust-mode#parinfer-rust-library][parinfer-rust]]. -This module has no prerequisites. - -* Features +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote ** Keybindings +| Binding | Description | +|-----------------+-------------------------------------------| +| [[kbd:][ p]] | Toggle between different inference modes. | +| [[kbd:][ P]] | Temporarily disable parinfer. | -| Binding | Description | -|-------------------+-------------------------------------------| -| ~ m p~ | Toggle between different inference modes. | -| ~ m P~ | Temporarily disable parinfer. | - -* Configuration -# How to configure this module, including common problems and how to address them. +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -# Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/rotate-text/README.org b/modules/editor/rotate-text/README.org index 390ee6e97..dc55769c0 100644 --- a/modules/editor/rotate-text/README.org +++ b/modules/editor/rotate-text/README.org @@ -1,52 +1,78 @@ -#+TITLE: editor/rotate-text -#+DATE: October 14, 2021 -#+SINCE: v2.0.4 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :editor rotate-text +#+subtitle: The only back'n'forth nerds will ever know +#+created: June 22, 2018 +#+since: 2.0.4 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - -* Description -# A summary of what this module does. -Provides a convenient way to rotate trough a set of related entities using a single key binding. There are both globally available sets as well as mode local once. For example the sequence ~enable~ and ~disable~ is globally available whereas the sequence ~public~, ~protected~ and ~private~ is only available in ~c++~ mode. +* Description :unfold: +This module adds text rotation to Doom Emacs. I.e. The ability to cycle through +keywords or text patterns at point, like ~true~ and ~false~, or ~public~, +~protected~, and ~private~ (in ~c++-mode~). ** Maintainers -# If this module has no maintainers, then... -This module has no dedicated maintainers. +- [[doom-user:][@hlissner]] -** Module Flags -# If this module has no flags, then... -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/debug-ito/rotate-text.el][rotate-text.el]] +** Module flags +/This module has no flags./ -* Prerequisites -This module has no prerequisites. +** Packages +- [[doom-package:][rotate-text]] -* Features -# An in-depth list of features, how to use them, and their dependencies. -With point on a word or symbol that is part of a sequence you can call ~rotate-text~ or ~rotate-text-backward~ to rotate to the next or previous item in the sequence. The list of items will wrap around as you cycle through them. +** Hacks +/No hacks documented for this module./ -* Configuration -To enable a set of items to cycle through globally, add the following to your configuration +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote +πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +For evil users: [[kbd:][[r]] and [[kbd:][]r]] will cycle back and forward (respectively) through +specified patterns for the text at point. Patterns will wrap around as you cycle +through them. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +To enable a set of items to cycle through globally: #+begin_src emacs-lisp -;; in ~/.doom.d/config.el +;; in $DOOMDIR/config.el (after! rotate-text - (pushnew! rotate-text-words '("small" "medium" "large"))) + (add-to-list 'rotate-text-words '("small" "medium" "large"))) #+end_src -To add a sequence to a specific mode, you can add something like the following to your configuration +To add a sequence to a specific mode: #+begin_src emacs-lisp -;; in ~/.doom.d/config.el +;; in $DOOMDIR/config.el (set-rotate-patterns! 'c++-mode :words '(("float" "double"))) -#+end_src +#+end_src -When configuring a sequence of words or symbols that should be rotated through, it is important that all items are all lower case. The casing will be determined by the item that initiated the rotation. For example, ~Small~ will be replaced with ~Medium~ and ~SMALL~ will be replaced with ~MEDIUM~ using the example described above. +When configuring a sequence of words or symbols that should be rotated through, +it is important that all items are all lower case. The casing will be determined +by the item that initiated the rotation. For example, ~Small~ will be replaced +with ~Medium~ and ~SMALL~ will be replaced with ~MEDIUM~ using the example +described above. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/snippets/README.org b/modules/editor/snippets/README.org index a5b3b955e..23946a4ec 100644 --- a/modules/editor/snippets/README.org +++ b/modules/editor/snippets/README.org @@ -1,46 +1,67 @@ -#+TITLE: editor/snippets -#+DATE: February 11, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :editor snippets +#+subtitle: My elves type so I don't have to +#+created: February 11, 2017 +#+since: 2.0.0 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#disabling-the-built-in-snippets][Disabling the built-in snippets]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module adds snippet expansions to Emacs, powered by [[doom-package:][yasnippet]]. -* Description -This module adds snippets to Emacs, powered by yasnippet. +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module exposes no flags. +** Module flags +/This module exposes no flags./ -** Plugins -+ [[https://github.com/joaotavora/yasnippet][yasnippet]] -+ [[https://github.com/abo-abo/auto-yasnippet][auto-yasnippet]] -+ [[https://github.com/hlissner/doom-snippets][doom-snippets]] +** Packages +- [[doom-package:][yasnippet]] +- [[doom-package:][auto-yasnippet]] +- [[doom-package:][doom-snippets]] ** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote -* Prerequisites -This module has no external dependencies. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* TODO Features +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Disabling the built-in snippets -Don't want to use provided one? Then add this to your private module, - -#+BEGIN_SRC emacs-lisp -;; in ~/.doom.d/packages.el +#+begin_src emacs-lisp +;; in $DOOMDIR/packages.el (package! doom-snippets :ignore t) ;; If you want to replace it with yasnippet's default snippets (package! yasnippet-snippets) -#+END_SRC +#+end_src -* TODO Troubleshooting +** Adding custom snippets +Custom snippets should be added under =$DOOMDIR/snippets/= directory. Refer to [[http://joaotavora.github.io/yasnippet/snippet-development.html][yasnippet-documentation]] on how to write snippets. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/editor/word-wrap/README.org b/modules/editor/word-wrap/README.org index 1f21da495..062cd2776 100644 --- a/modules/editor/word-wrap/README.org +++ b/modules/editor/word-wrap/README.org @@ -1,17 +1,80 @@ -#+TITLE: editor/word-wrap -#+DATE: August 26, 2019 -#+SINCE: v2.1 +# -*- mode: doom-docs-org -*- +#+title: :editor word-wrap +#+subtitle: Soft-wrapping with language-aware indent +#+created: August 25, 2019 +#+since: 21.12.0 (#1709) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#configuration][Configuration]] - -* Description -This module adds a minor-mode ~+word-wrap-mode~, which intelligently wraps long +* Description :unfold: +This module adds a minor-mode [[fn:][+word-wrap-mode]], which intelligently wraps long lines in the buffer without modifying the buffer content. +** Maintainers +- [[doom-user:][@flatwhatson]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][adaptive-wrap]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +** Activation +Word wrapping is not enabled by default. + +Wrapping can be toggled in the current buffer with ~M-x +word-wrap-mode~. The +default doom bindings bind this to [[kbd:][SPC t w]] for ~evil~ users. + +To enable wrapping in a specific mode, add it to the appropriate hook in your +~config.el~: +#+begin_src emacs-lisp +;; enable word-wrap in C/C++/ObjC/Java +(add-hook 'c-mode-common-hook #'+word-wrap-mode) +#+end_src + +To customize the behaviour in a specific mode: +#+begin_src emacs-lisp +;; use a single indent in json-mode +(add-hook! 'json-mode-hook + (setq-local +word-wrap-extra-indent 'single) + (+word-wrap-mode +1)) +#+end_src + +To turn on word wrapping (almost) everywhere: +#+begin_src emacs-lisp +;; enable word-wrap (almost) everywhere +(+global-word-wrap-mode +1) +#+end_src + +To disable global word-wrapping in a specific mode: +#+begin_src emacs-lisp +;; disable global word-wrap in emacs-lisp-mode +(add-to-list '+word-wrap-disabled-modes 'emacs-lisp-mode) +#+end_src + +** Settings Wrapped lines will be indented to match the preceding line. In code buffers, lines which are not inside a string or comment will have extra indentation as determined by ~+word-wrap-extra-indent~. The default is to increase the indent @@ -37,45 +100,13 @@ The ~+word-wrap-visual-modes~ variable lists modes which should only enable ~visual-line-mode~ and not provide any prefix indentation. This is useful for modes like ~org-mode~ which handle prefix indentation themselves. -** Module Flags -This module provides no flags. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] -** Plugins -+ [[https://elpa.gnu.org/packages/adaptive-wrap.html][adaptive-wrap]] +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] -* Configuration -Word wrapping is not enabled by default. - -Wrapping can be toggled in the current buffer with ~M-x +word-wrap-mode~. The -default doom bindings bind this to ~SPC t w~ for ~evil~ users. - -To enable wrapping in a specific mode, add it to the appropriate hook in your -~config.el~: - -#+BEGIN_SRC emacs-lisp -;; enable word-wrap in C/C++/ObjC/Java -(add-hook 'c-mode-common-hook #'+word-wrap-mode) -#+END_SRC - -To customize the behaviour in a specific mode: - -#+BEGIN_SRC emacs-lisp -;; use a single indent in json-mode -(add-hook! 'json-mode-hook - (setq-local +word-wrap-extra-indent 'single) - (+word-wrap-mode +1)) -#+END_SRC - -To turn on word wrapping (almost) everywhere: - -#+BEGIN_SRC emacs-lisp -;; enable word-wrap (almost) everywhere -(+global-word-wrap-mode +1) -#+END_SRC - -To disable global word-wrapping in a specific mode: - -#+BEGIN_SRC emacs-lisp -;; disable global word-wrap in emacs-lisp-mode -(add-to-list '+word-wrap-disabled-modes 'emacs-lisp-mode) -#+END_SRC +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/emacs/README.org b/modules/emacs/README.org new file mode 100644 index 000000000..cc9ed6289 --- /dev/null +++ b/modules/emacs/README.org @@ -0,0 +1,10 @@ +# -*- mode: doom-docs-org -*- +#+title: :emacs +#+created: August 01, 2021 +#+since: 21.12.0 + +* Description +Modules in this category augment and extend the built-in features of Emacs. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/emacs/dired/README.org b/modules/emacs/dired/README.org index 0a458c340..f09d3b8c3 100644 --- a/modules/emacs/dired/README.org +++ b/modules/emacs/dired/README.org @@ -1,49 +1,75 @@ -#+TITLE: emacs/dired -#+DATE: May 27, 2018 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :emacs dired +#+subtitle: Making dired pretty [functional] +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#keybindings][Keybindings]] - - [[#ranger][Ranger]] +* Description :unfold: +This module provides reasonable defaults and augmentations for dired. -* Description -This module provides configuration for dired. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+ranger= Enables dired to be more like [[https://github.com/ranger/ranger][ranger]]. -+ =+icons= Enables the display of fancy icons depending on file types in dired - buffers. +** Module flags +- +icons :: + Enables the display of fancy icons depending on file types in dired buffers. +- +ranger :: + Enables dired to be more like [[https://github.com/ranger/ranger][ranger]]. -** Plugins -+ [[https://github.com/purcell/diredfl][diredfl]] -+ [[https://github.com/stsquad/dired-rsync][dired-rsync]] -+ [[https://github.com/dgutov/diff-hl/][diff-hl]] -+ [[https://github.com/yqrashawn/fd-dired][fd-dired]] -+ =+ranger= - + [[https://github.com/ralesi/ranger.el][ranger]] -+ =+icons= - + [[https://github.com/jtbm37/all-the-icons-dired][all-the-icons-dired]] +** Packages +- [[doom-package:][all-the-icons-dired]] if [[doom-module:][+icons]] +- [[doom-package:][diff-hl]] +- [[doom-package:][diredfl]] +- [[doom-package:][dired-rsync]] +- [[doom-package:][fd-dired]] +- [[doom-package:][ranger]] if [[doom-module:][+ranger]] -* Prerequisites -This module has no prerequisites *except on BSDs* where =GNU ls= (~gls~) is -needed for it to work properly (Doom doctor will notify you if it is missing). +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote -* Keybindings -| Keybind | Description | -|-----------+------------------------------| -| =SPC f d= | Find directory with dired | -| =q= | Exit dired buffer | -| =C-c C-r= | Run =dired-rsync= | -| =C-c C-e= | Rename entries with =wdired= | +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has no requirements *except on BSDs* like MacOS or FreeBSD, where +=GNU ls= (aka ~gls~) is required. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +| Keybind | Description | +|---------+----------------------------| +| [[kbd:][SPC f d]] | Find directory with dired | +| [[kbd:][q]] | Exit dired buffer | +| [[kbd:][C-c C-r]] | Run [[doom-package:][dired-rsync]] | +| [[kbd:][C-c C-e]] | Rename entries with [[doom-package:][wdired]] | Other keybindings can be found on the official [[https://www.gnu.org/software/emacs/refcards/pdf/dired-ref.pdf][Dired reference card]]. ** Ranger -If =+ranger= is enabled often a buffer will be opened in minimal ranger mode -(deer-mode). In this case =z P= can be used to toggle between full ranger and -deer-mode. +If [[doom-module:][+ranger]] is enabled often a buffer will be opened in minimal ranger mode +(~deer-mode~). In this case [[kbd:][z P]] can be used to toggle between full ranger and +~deer-mode~. + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/emacs/electric/README.org b/modules/emacs/electric/README.org new file mode 100644 index 000000000..897286dea --- /dev/null +++ b/modules/emacs/electric/README.org @@ -0,0 +1,55 @@ +# -*- mode: doom-docs-org -*- +#+title: :emacs electric +#+subtitle: Shocking keyword-based electric-indent +#+created: February 21, 2017 +#+since: 2.0.0 + +* Description :unfold: +This module augments the built-in [[doom-package:][electric]] package with keyword-based +indentation (as opposed to character-based). + +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +/This module doesn't install any packages./ + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/emacs/ibuffer/README.org b/modules/emacs/ibuffer/README.org index e3a85f454..3aafe266c 100644 --- a/modules/emacs/ibuffer/README.org +++ b/modules/emacs/ibuffer/README.org @@ -1,36 +1,58 @@ -#+TITLE: emacs/ibuffer -#+DATE: October 20, 2019 -#+SINCE: v2.1.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :emacs ibuffer +#+subtitle: Edit me like one of your French buffers +#+created: October 20, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module augments the built-in [[doom-package:][ibuffer]] package. -* Description -This module augments ibuffer. +- Adds project-based grouping of buffers +- Support for file-type icons +- Uses human-readable file-size -+ Adds project-based grouping of buffers -+ Support for file-type icons -+ Uses human-readable file-size +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+icons= Enables filetype icons for buffers +** Module flags +- +icons :: + Enable filetype icons for buffers using [[doom-package:][all-the-icons]]. -** Plugins -+ [[https://github.com/purcell/ibuffer-projectile][ibuffer-projectile]] -+ [[https://github.com/purcell/ibuffer-vc][ibuffer-vc]] +** Packages +- [[doom-package:][ibuffer-projectile]] +- [[doom-package:][ibuffer-vc]] -* Prerequisites -This module has no prerequisites. +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote -* TODO Features +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/emacs/undo/README.org b/modules/emacs/undo/README.org index ad8e36a0c..cec1bd61a 100644 --- a/modules/emacs/undo/README.org +++ b/modules/emacs/undo/README.org @@ -1,68 +1,84 @@ -#+TITLE: emacs/undo -#+DATE: April 13, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :emacs undo +#+subtitle: Persistent, smarter undo for your inevitable mistakes +#+created: April 14, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#disabling-persistent-undo-history][Disabling persistent undo history]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module augments Emacs' built-in undo system to be more intuitive and to persist across Emacs sessions. ** Maintainers -This module has no dedicated maintainers. +- [[doom-user:][@hlissner]] -** Module Flags -+ =+tree= Uses ~undo-tree~ instead of ~undo-fu~, which is a little less stable, - but offers branching undo history and a visualizer for navigating it. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://gitlab.com/ideasman42/emacs-undo-fu][undo-fu]] -+ [[https://gitlab.com/ideasman42/emacs-undo-fu-session][undo-fu-session]] -+ [[https://github.com/emacsmirror/undo-tree][undo-tree]] (=+tree=) +** Module flags +- +tree :: + Uses [[doom-package:][undo-tree]] instead of [[doom-package:][undo-fu]], which is a little less stable, but offers + branching undo history and a visualizer for navigating it. + +** Packages +- [[doom-package:][undo-fu]] +- [[doom-package:][undo-fu-session]] +- [[doom-package:][undo-tree]] if [[doom-module:][+tree]] ** Hacks -+ Both undo-fu and undo-tree have been modified to use zstd to compress undo +- Both undo-fu and undo-tree have been modified to use =zstd= to compress undo history if it is available. -+ undo-tree only - + Text properties are stripped from undo history to shrink it. - + Undo-tree is too chatty about saving its history files. This has be +- undo-tree only + - Text properties are stripped from undo history to shrink it. + - Undo-tree is too chatty about saving its history files. This has be "silenced". i.e. It's visible in \*Messages\*, but won't appear in your minibuffer. -+ unfo-fu only - + Doom defines =undo-fu-mode= to make it easier to add hooks/mode-local +- unfo-fu only + - Doom defines ~undo-fu-mode~ to make it easier to add hooks/mode-local keybinds. -* Prerequisites -This module has no prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Disabling persistent undo history -+ If you are using =+tree=: - - #+BEGIN_SRC elisp +- If you are using [[doom-module:][+tree]]: + #+begin_src emacs-lisp (after! undo-tree (setq undo-tree-auto-save-history nil)) - #+END_SRC + #+end_src -+ If you aren't: - - #+BEGIN_SRC elisp +- If you aren't: + #+begin_src emacs-lisp (remove-hook 'undo-fu-mode-hook #'global-undo-fu-session-mode) - #+END_SRC + #+end_src -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* Troubleshooting +[[doom-report:][Report an issue?]] + +** undo-tree +- Has been known to truncate undo history unpredictably, due to Emacs' undo + cleanup imposing linear undo limits on non-linear undo tree data. Doom already + sets ~undo-limit~, ~undo-strong-limit~, and ~undo-outer-limit~ absurdly high + to mitigate this somewhat. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/emacs/vc/README.org b/modules/emacs/vc/README.org index ce7bef7c3..b919127a2 100644 --- a/modules/emacs/vc/README.org +++ b/modules/emacs/vc/README.org @@ -1,42 +1,61 @@ -#+TITLE: emacs/vc -#+DATE: May 23, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :emacs vc +#+subtitle: Be the difference you want to see in the fringe +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This module augments Emacs builtin version control support and provides better integration with git +* Description :unfold: +This module augments Emacs builtin version control support and provides better +integration with =git=. ** Maintainers -This module has no dedicated maintainers. +- [[doom-user:][@hlissner]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -# A list of linked plugins -+ [[https://github.com/rmuslimov/browse-at-remote][browse-at-remote]] -+ [[https://gitlab.com/pidu/git-timemachine][git-timemachine]] -+ [[https://github.com/magit/git-modes][gitconfig-mode]] -+ [[https://github.com/magit/git-modes][gitignore-mode]] +** Module flags +/This module has no flags./ -* Prerequisites -This module has no prerequisites. +** Packages +- [[doom-package:][browse-at-remote]] +- [[doom-package:][git-timemachine]] +- [[doom-package:][gitconfig-mode]] +- [[doom-package:][gitignore-mode]] -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +** Hacks +- Allow [[doom-package:][browse-at-remote]] commands in [[doom-package:][git-timemachine]] buffers to open that file + in your browser at the visited revision. +- [[doom-package:][git-timemachine]] buffers will display revision details in the header-line, + rather than the minibuffer (easier to see). +- [[doom-package:][browse-at-remote]] will fall back to the =master= branch if target is in a + detached state. + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module only requires [[https://git-scm.com/][Git]]. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration -# How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/email/README.org b/modules/email/README.org new file mode 100644 index 000000000..6766832a8 --- /dev/null +++ b/modules/email/README.org @@ -0,0 +1,10 @@ +# -*- mode: doom-docs-org -*- +#+title: :email +#+created: October 14, 2021 +#+since: 21.12.0 + +* Description +Modules that turn Emacs in an email client. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/email/mu4e/README.org b/modules/email/mu4e/README.org index 87bb25162..edb7e8664 100644 --- a/modules/email/mu4e/README.org +++ b/modules/email/mu4e/README.org @@ -1,79 +1,87 @@ -#+TITLE: email/mu4e -#+DATE: April 8, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :email mu4e +#+subtitle: The great filter Hanson hadn't anticipated +#+created: April 08, 2017 +#+since: 2.0.3 -* Table of Contents :TOC:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#nixos][NixOS]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#offlineimap][offlineimap]] - - [[#mbsync][mbsync]] - - [[#fetching-your-mail-in-other-ways][Fetching your mail in other ways]] - - [[#mu-and-mu4e][mu and mu4e]] - - [[#orgmsg][OrgMsg]] - - [[#mu4e-alert][mu4e-alert]] -- [[#troubleshooting][Troubleshooting]] - - [[#no-such-file-or-directory-mu4e][=No such file or directory, mu4e=]] - - [[#void-function-org-time-add-error-on-gentoo][~(void-function org-time-add)~ error on Gentoo]] - -* Description +* Description :unfold: This module makes Emacs an email client, using [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]]. -#+begin_quote -I want to live in Emacs, but as we all know, living is incomplete without email. -So I prayed to the text editor gods and they (I) answered. Emacs+evil's editing -combined with org-mode for writing emails? /Yes please./ +- Tidied mu4e headers view, with flags from [[doom-package:][all-the-icons]]. +- Consistent coloring of reply depths (across compose and gnus modes). +- Prettified =mu4e:main= view. +- Cooperative locking of the =mu= process. Another Emacs instance may request + access, or grab the lock when it's available. +- [[doom-package:][org-msg]] integration with [[doom-module:][+org]], which can be toggled per-message, with revamped + style and an accent color. +- Gmail integrations with the [[doom-module:][+gmail]] flag. +- Email notifications with [[doom-package:][mu4e-alert]], and (on Linux) a customised notification + style. -It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my email -via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can understand). +#+begin_quote + πŸ’‘ I want to live in Emacs, but as we all know, living is incomplete without + email. So I prayed to the text editor gods and they (I) answered. + Emacs+evil's editing combined with org-mode for writing emails? /Yes + please./ + + It uses ~mu4e~ to read my email, but depends on ~offlineimap~ (to sync my + email via IMAP) and ~mu~ (to index my mail into a format ~mu4e~ can + understand). #+end_quote ** Maintainers -+ [[https://github.com/tecosaur][@tecosaur]] +- [[doom-user:][@tecosaur]] -** Module Flags -+ =+gmail= Enables gmail-specific configuration for mail ~To~ or ~From~ a gmail - address, or a maildir with ~gmail~ in the name. -+ =+org= Use =org-msg= for composing email in Org, then sending a multipart text - (ASCII export) and HTML message. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/iqbalansari/mu4e-alert][mu4e-alert]] -+ =+org= - + [[https://github.com/jeremy-compostella/org-msg][org-msg]] +** Module flags +- +gmail :: + Enable gmail-specific configuration for mail ~To~ or ~From~ a gmail address, + or a maildir with ~gmail~ in the name. +- +org :: + Use [[doom-package:][org-msg]] for composing email in Org, then sending a multipart text (ASCII + export) and HTML message. + +** Packages +- [[doom-package:][mu4e-alert]] +- [[doom-package:][org-msg]] if [[doom-module:][+org]] + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites This module requires: -+ [[https://www.djcbsoftware.nl/code/mu/][mu]], to index your downloaded messages and to provide the [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]] package. -+ A program to sync your mail. This module comes with builtin support for - [[https://isync.sourceforge.io/][mbsync]] (recommended, default) or [[http://www.offlineimap.org/][offlineimap]] but you can sync mail in - other ways too. +- [[https://www.djcbsoftware.nl/code/mu/][mu]], to index your downloaded messages and to provide the [[https://www.djcbsoftware.nl/code/mu/mu4e.html][mu4e]] package. +- A program to sync your mail. This module comes with builtin support for [[https://isync.sourceforge.io/][mbsync]] + (recommended, default) or [[http://www.offlineimap.org/][offlineimap]] but you can sync mail in other ways too. #+name: Install Matrix -| Platform | Install command | Base packages | -|---------------+--------------------------+-------------------------| -| MacOS | ~brew install ~ | =mu= | -| Arch | ~pacman -S ~ | (AUR, ~yay -S~) =mu= | -| openSUSE | ~zypper install ~ | =maildir-utils=, =mu4e= | -| Fedora | ~dnf install ~ | =maildir-utils= | -| Debian/Ubuntu | ~apt-get install ~ | =maildir-utils=, =mu4e= | +| Platform | Install command | Base packages | +|---------------+----------------------------+-------------------------| +| MacOS | ~$ brew install ~ | =mu= | +| Arch | ~$ pacman -S ~ | (AUR, ~$ yay -S~) =mu= | +| openSUSE | ~$ zypper install ~ | =maildir-utils=, =mu4e= | +| Fedora | ~$ dnf install ~ | =maildir-utils= | +| Debian/Ubuntu | ~$ apt-get install ~ | =maildir-utils=, =mu4e= | Then install either the =isync= (=mbsync=) or =offlineimap= package. -To send mail, mu4e uses [[https://www.gnu.org/software/emacs/manual/html_mono/smtpmail.html][smtpmail]] (an Emacs library) by default. -You can also run a local SMTP server like =sendmail= or =postfix=, or use an SMTP -forwarder such as =msmtp= (recommended). +To send mail, mu4e uses [[https://www.gnu.org/software/emacs/manual/html_mono/smtpmail.html][smtpmail]] (an Emacs library) by default. You can also run +a local SMTP server like =sendmail= or =postfix=, or use an SMTP forwarder such +as =msmtp= (recommended). -If you use =msmtp=, you'll likely want to add the following to your -=config.el=: +If you use =msmtp=: #+begin_src emacs-lisp +;; add to $DOOMDIR/config.el (after! mu4e (setq sendmail-program (executable-find "msmtp") send-mail-function #'smtpmail-send-it @@ -83,42 +91,40 @@ If you use =msmtp=, you'll likely want to add the following to your #+end_src ** NixOS -#+BEGIN_SRC nix +#+begin_src nix environment.systemPackages = with pkgs; [ mu # And one of the following isync offlineimap ]; -#+END_SRC +#+end_src [[https://github.com/Emiller88/dotfiles/blob/5eaabedf1b141c80a8d32e1b496055231476f65e/modules/shell/mail.nix][An example of setting up mbsync and mu with home-manager]] -* Features -+ Tidied mu4e headers view, with flags from =all-the-icons= -+ Consistent coloring of reply depths (across compose and gnus modes) -+ Prettified =mu4e:main= view -+ Cooperative locking of the =mu= process. Another Emacs instance may request - access, or grab the lock when it's available. -+ =org-msg= integration with =+org=, which can be toggled per-message, with revamped style and - an accent color -+ Gmail integrations with the =+gmail= flag -+ Email notifications with =mu4e-alert=, and (on Linux) a customised notification style +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** offlineimap -This module uses =mbsync= by default. To use =offlineimap=, change ~+mu4e-backend~: - -#+BEGIN_SRC emacs-lisp +This module uses =mbsync= by default. To use =offlineimap=, change +~+mu4e-backend~: +#+begin_src emacs-lisp (setq +mu4e-backend 'offlineimap) -#+END_SRC +#+end_src -Next, you need to write a configuration file for =offlineimap=. Mine can be found -[[https://github.com/hlissner/dotfiles/blob/be0dce5dae8f3cbafaac0cc44269d84b4a742c46/shell/mu/][in my dotfiles repository]]. It is configured to download mail to ~\~/.mail~. I -use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. You can find a *very* -detailed configuration [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][here]]. +Next, you need to write a configuration file for =offlineimap=. Mine can be +found [[https://github.com/hlissner/dotfiles/blob/be0dce5dae8f3cbafaac0cc44269d84b4a742c46/shell/mu/][in my dotfiles repository]]. It is configured to download mail to +~\~/.mail~. I use [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. You can find +a *very* detailed configuration [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][here]]. -Next you can download your email with ~offlineimap -o~. This may take a while, +Next you can download your email with ~$ offlineimap -o~. This may take a while, especially if you have thousands of mails. You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section. @@ -127,12 +133,12 @@ You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section. The steps needed to set up =mu4e= with =mbsync= are very similar to the ones for [[#offlineimap][offlineimap]]. -Start with writing a ~~/.mbsyncrc~. An example for Gmail can be found on +Start with writing a =~/.mbsyncrc=. An example for Gmail can be found on [[http://pragmaticemacs.com/emacs/migrating-from-offlineimap-to-mbsync-for-mu4e/][pragmaticemacs.com]]. A non-Gmail example is available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. The [[http://isync.sourceforge.net/mbsync.html][manual page]] contains all needed information to set up your own. -Next you can download your email with ~mbsync --all~. This may take a while, but -should be quicker than =offlineimap= ;). +Next you can download your email with ~$ mbsync --all~. This may take a while, +but should be quicker than =offlineimap= ;). You can now proceed with the [[#mu-and-mu4e][mu and mu4e]] section. @@ -142,19 +148,20 @@ tailored =mbsync= command to just fetch the new changes. If this is of interest, this approach can be seen [[https://tecosaur.github.io/emacs-config/config.html#fetching][in @tecosaur's config]] where [[https://gitlab.com/shackra/goimapnotify][goimapnotify]] is used for this. + ** Fetching your mail in other ways You also have the possiblity to invoke an arbitary shell command to fetch your mail by disabling this module's backend selection and setting the value of the -~mu4e-get-mail-command~ to the command you want to execute. -#+BEGIN_SRC emacs-lisp +~mu4e-get-mail-command~ to the command you want to execute: +#+begin_src emacs-lisp (setq +mu4e-backend nil) (after! mu4e (setq mu4e-get-mail-command "your_command")) -#+END_SRC +#+end_src If your command prompts you for a passphrase, you might want to change the value -of the ~mu4e~get-mail-password-regexp~ such that =mu4e= will recognize the -prompt and let you provide the passphrase from within Emacs. +of the ~mu4e~get-mail-password-regexp~ such that [[doom-package:][mu4e]] will recognize the prompt +and let you provide the passphrase from within Emacs. ** mu and mu4e You should have your email downloaded already. If you have not, you need to set @@ -162,24 +169,23 @@ You should have your email downloaded already. If you have not, you need to set Before you can use =mu4e= or the CLI program =mu=, you need to index your email initially. How to do that differs a little depending on the version of =mu= you -use. You can check your version with ~mu --version~. +use. You can check your version with ~$ mu --version~. For =mu= *>=1.4* you need to run two commands: -#+BEGIN_SRC sh +#+begin_src sh mu init --maildir ~/.mail --my-address email@example.com mu index -#+END_SRC +#+end_src =mu= *<1.4* only requires one command: -#+BEGIN_SRC sh -mu index --maildir ~/.mail -#+END_SRC +#+begin_src sh +mu index --maildir $HOME/.mail +#+end_src -Be sure to replace ~~/.mail~ with the directory containing your mail. +Be sure to replace =$HOME/.mail= with the directory containing your mail. Then configure Emacs to use your email address: - -#+BEGIN_SRC emacs-lisp :tangle no +#+begin_src emacs-lisp ;; Each path is relative to the path of the maildir you passed to mu (set-email-account! "bar.com" '((mu4e-sent-folder . "/bar.com/Sent Mail") @@ -190,14 +196,13 @@ Then configure Emacs to use your email address: (user-mail-address . "foo@bar.com") ;; only needed for mu < 1.4 (mu4e-compose-signature . "---\nYours truly\nThe Baz")) t) -#+END_SRC +#+end_src If you use multiple email accounts, defining them with ~set-email-account!~ will automatically set the appropriate account context when replying to emails in that account's maildir. ~mu4e-context-policy~ and ~mu4e-compose-context-policy~ can be modified to change context behavior when opening mu4e and composing email: - #+begin_src emacs-lisp (setq mu4e-context-policy 'ask-if-none mu4e-compose-context-policy 'always-ask) @@ -209,7 +214,7 @@ you are not replying to an email to or from one of the specified aliases, you will be prompted for an alias to send from. *** Gmail -With the =+gmail= flag, integrations are applied which account for the different +With the [[doom-module:][+gmail]] flag, integrations are applied which account for the different behaviour of Gmail. The integrations are applied to addresses with /both/ "@gmail.com" in the @@ -222,8 +227,8 @@ benefit from the integrations: ("example@example.com" . "/example"))) #+end_src -If you only use Gmail, you can improve performance due to the way Gmail -presents messages over IMAP: +If you only use Gmail, you can improve performance due to the way Gmail presents +messages over IMAP: #+begin_src emacs-lisp ;; don't need to run cleanup after indexing for gmail (setq mu4e-index-cleanup nil @@ -238,14 +243,15 @@ as deleted: Auto-Expunge off - Wait for the client to update the server." and folder: Move the message to the trash" for the integrations to work as expected. ** OrgMsg -With the =+org= flag, =org-msg= is installed, and ~org-msg-mode~ is enabled before -composing the first message. To disable ~org-msg-mode~ by default, simply -#+BEGIN_SRC emacs-lisp :tangle no -(setq mu4e-compose--org-msg-toggle-next nil) -#+END_SRC +With the [[doom-module:][+org]] flag, [[doom-package:][org-msg]] is installed, and ~org-msg-mode~ is enabled before +composing the first message. To disable ~org-msg-mode~ by default: +#+begin_src emacs-lisp +;; add to $DOOMDIR/config.el +(setq +mu4e-compose-org-msg-toggle-next nil) +#+end_src To toggle org-msg for a single message, just apply the universal argument to the -compose or reply command (=SPC u= with ~evil~, =C-u= otherwise). +compose or reply command ([[kbd:][SPC u]] with [[doom-package:][evil]], [[kbd:][C-u]] otherwise). The accent color that Doom uses can be customised by setting ~+org-msg-accent-color~ to a CSS color string. @@ -253,35 +259,44 @@ The accent color that Doom uses can be customised by setting ** mu4e-alert This provides notifications through the [[https://github.com/jwiegley/alert][alert]] library. -If you don't like this, simply add +If you don't like this use: #+begin_src emacs-lisp +;; add to $DOOMDIR/packages.el (package! mu4e-alert :disable t) #+end_src -to your [[elisp:(find-file (expand-file-name "packages.el" doom-private-dir))][packages.el]] and it will not be used. + +** Enabling automatic email fetching +By default, periodic email update is *disabled*. To enable periodic +mail retrieval/indexing, change the value of ~mu4e-update-interval~: + +#+begin_src emacs-lisp +(setq mu4e-update-interval 60) +#+end_src * Troubleshooting +[[doom-report:][Report an issue?]] + ** =No such file or directory, mu4e= -You will get =No such file or directory, mu4e= errors if you don't run ~doom +You will get =No such file or directory, mu4e= errors if you don't run ~$ doom sync~ after installing =mu= through your package manager. -Some times the the ~mu~ package does not include ~mu4e~ (*cough Ubuntu*). -if that's the case you will need to [[https://github.com/djcb/mu][install]] it and add it to your ~load-path~ -you can do that by... -#+BEGIN_SRC emacs-lisp :tangle no +Some times the the ~mu~ package does not include ~mu4e~ (*cough Ubuntu*). if +that's the case you will need to [[https://github.com/djcb/mu][install]] it and add it to your ~load-path~ you +can do that by: +#+begin_src emacs-lisp (add-to-list 'load-path "your/path/to/mu4e") ;; if you installed it using your package manager (add-to-list 'load-path "/usr/share/emacs/site-lisp/mu4e") ;; if you built from source (add-to-list 'load-path "/usr/local/share/emacs/site-lisp/mu4e") -#+END_SRC +#+end_src -If you have completely lost your install then you can use this handy command! - -#+BEGIN_SRC shell +If you have completely lost your install then you can use: +#+begin_src sh find / -type d -iname '*mu4e*' # I recommend rerouting all of the errors to /dev/null find / -type d -iname '*mu4e*' 2> /dev/null -#+END_SRC +#+end_src ** ~(void-function org-time-add)~ error on Gentoo Gentoo users will see this error because [[https://gitweb.gentoo.org/repo/gentoo.git/tree/net-mail/mu/files/70mu-gentoo.el#n2][the =net-mail/mu= package eagerly loads @@ -291,3 +306,11 @@ version that Doom installs. Later versions of the =net-mail/mu= package have [[https://gitweb.gentoo.org/repo/gentoo.git/commit/net-mail/mu?id=770e1fccb119fbce8ba6d16021a3598123f212ff][fixed this issue]], but you may need to switch to the unstable build of =net-mail/mu= to see it. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/email/notmuch/README.org b/modules/email/notmuch/README.org index b559e5119..ec38cc77a 100644 --- a/modules/email/notmuch/README.org +++ b/modules/email/notmuch/README.org @@ -1,62 +1,60 @@ -#+TITLE: email/notmuch -#+DATE: May 5, 2019 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :email notmuch +#+subtitle: Closest Emacs will ever be to multi-threaded +#+created: July 31, 2018 +#+since: 21.12.0 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#macos][MacOS]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] - - [[#opensuse][openSUSE]] - - [[#debianubuntu][Debian/Ubuntu]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#downloading-your-email][Downloading your email]] - - [[#sending-mail][Sending mail]] - - [[#customize-notmuch-hello-buffer][Customize =*notmuch-hello*= buffer]] - - [[#changing-the-notmuch-landing-page][Changing the =notmuch= landing page]] - - [[#writing-html-emails][Writing HTML Emails]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module turns Emacs into an email client using [[doom-package:][notmuch]]. -* Description -This module turns Emacs into an email client using [[https://notmuchmail.org/][notmuch]]. +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+org= Enables org-mime for writing HTML emails using org-mode. -+ =+afew= Enables integration with =afew=. +** Module flags +- +afew :: + Enable integration with [[https://github.com/afewmail/afew][afew]]. +- +org :: + Enable [[doom-package:][org-mime]] for writing HTML emails using org-mode. -** Plugins -+ [[https://notmuchmail.org/][notmuch]] -+ [[https://github.com/org-mime/org-mime][org-mime]]* (with =+org= flag) -+ [[https://github.com/fuxialexander/counsel-notmuch][counsel-notmuch]]* -+ [[https://github.com/emacs-helm/helm-notmuch][helm-notmuch]]* +** Packages +- [[doom-package:][counsel-notmuch]] if [[doom-module:][:completion ivy]] +- [[doom-package:][helm-notmuch]] if [[doom-module:][:completion helm]] +- [[doom-package:][notmuch]] +- [[doom-package:][org-mime]]* if [[doom-module:][+org]] + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites This module requires: -+ Either [[https://github.com/gauteh/lieer][gmailieer]] (default), [[https://isync.sourceforge.io/][mbsync]] or [[http://www.offlineimap.org/][offlineimap]] (to sync mail with) -+ [[https://notmuchmail.org/][notmuch]], to index and tag your downloaded messages. -+ [[https://github.com/afewmail/afew][afew]] , optionally to initially tag your downloaded messages. ++ Either [[https://github.com/gauteh/lieer][gmailieer]] (default), [[https://isync.sourceforge.io/][mbsync]] or [[http://www.offlineimap.org/][offlineimap]] -- to sync mail with. ++ [[https://notmuchmail.org/][notmuch]] -- to index and tag your downloaded messages. ++ [[https://github.com/afewmail/afew][afew]] -- optionally to initially tag your downloaded messages. + ** TODO MacOS ** Arch Linux -Run one of the following commands. - -#+BEGIN_SRC sh +Run one of the following commands: +#+begin_src sh pacman -S isync notmuch #mbsync -#+END_SRC -#+BEGIN_SRC sh +#+end_src +#+begin_src sh pacman -S offlineimap notmuch -#+END_SRC +#+end_src See: [[https://wiki.archlinux.org/index.php/Notmuch][Arch Wiki - Notmuch]] ** NixOS -#+BEGIN_SRC nix +#+begin_src nix environment.systemPackages = with pkgs; [ notmuch # And one of the following @@ -64,20 +62,28 @@ environment.systemPackages = with pkgs; [ isync offlineimap ]; -#+END_SRC +#+end_src [[https://github.com/Emiller88/dotfiles/blob/319841bd3b89e59b01d169137cceee3183aba4fc/modules/shell/mail.nix][An example of setting up mbsync and notmuch with home-manager]] ** TODO openSUSE ** TODO Debian/Ubuntu -* Features +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -| Keymap | Command | Description | -| ~SPC m u~ | =+notmuch/update= | Download, sync, and index emails with notmuch | -| ~SPC m c~ | =+notmuch/compose= | Compose new email | +| Keymap | Command | Description | +|-----------------+--------------------+-----------------------------------------------| +| [[kbd:][ u]] | ~+notmuch/update~ | Download, sync, and index emails with notmuch | +| [[kbd:][ c]] | ~+notmuch/compose~ | Compose new email | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Downloading your email To download your email you need a sync backend. Out of the box, this module supports =Gmailier= (the default), =mbsync=, and =offlineimap= (ordered by @@ -86,109 +92,118 @@ through setting them up with notmuch. Later, once you've set up a sync backend and downloaded your email, you must index your email for the first time: - -#+BEGIN_SRC sh +#+begin_src sh notmuch new -#+END_SRC +#+end_src *** lieer - -[[https://github.com/gauteh/lieer][Lieer]], formerly called Gmailieer, is the indexing tool used by default. To install lieer, see the [[https://github.com/gauteh/lieer#installation][installation docs]]. +[[https://github.com/gauteh/lieer][Lieer]], formerly called Gmailieer, is the indexing tool used by default. To +install lieer, see the [[https://github.com/gauteh/lieer#installation][installation docs]]. *** offlineimap To use [[https://www.offlineimap.org/][offlineimap]], change ~+notmuch-sync-backend~: - -#+BEGIN_SRC emacs-lisp -;; add to ~/.doom.d/config.el +#+begin_src emacs-lisp +;; add to $DOOMDIR/config.el (setq +notmuch-sync-backend 'offlineimap) -#+END_SRC +#+end_src Next, write a configuration file for =offlineimap=. [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf][Here is a comprehensive example]] and [[https://github.com/OfflineIMAP/offlineimap/blob/master/offlineimap.conf.minimal][another minimal one]]. As a real world example, [[https://github.com/hlissner/dotfiles/blob/5f146b6c39552c0cf38025406f5dba7389542b0a/shell/mu/.offlineimaprc][here is my old config]], where it is configured to -download mail to ~\~/.mail~. I used [[https://www.passwordstore.org/][unix pass]] to securely store my login +download mail to =$HOME/.mail=. I used [[https://www.passwordstore.org/][unix pass]] to securely store my login credentials. -Finally, download your email with ~offlineimap -o~. This may take a while, +Finally, download your email with ~$ offlineimap -o~. This may take a while, especially if you have thousands of emails. *** mbsync To use [[https://isync.sourceforge.io/][mbsync]], change ~+notmuch-sync-backend~: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (setq +notmuch-sync-backend 'mbsync) ;; Use `mbsync-xdg' if your mbsync config lives in $XDG_CONFIG_HOME/isync: (setq +notmuch-sync-backend 'mbsync-xdg) -#+END_SRC +#+end_src The steps needed to set up =notmuch= with =mbsync= are similar to the ones for [[*offlineimap][offlineimap]]. -Start with writing a ~\~/.mbsyncrc~ to store your configuration. An example for -GMAIL can be found on the [[https://wiki.archlinux.org/index.php/isync#Configuring][ArchWiki]] which will also explain how its integration -with notmuch for auto synchronization. A non-GMAIL example is available as a -gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. +Start with writing a =$HOME/.mbsyncrc= to store your configuration. An example +for GMAIL can be found on the [[https://wiki.archlinux.org/index.php/isync#Configuring][ArchWiki]] which will also explain how its +integration with notmuch for auto synchronization. A non-GMAIL example is +available as a gist [[https://gist.github.com/agraul/60977cc497c3aec44e10591f94f49ef0][here]]. -Finally, download your email with ~mbsync --all~. This may take a while, but +Finally, download your email with ~$ mbsync --all~. This may take a while, but will be quicker than =offlineimap=. *** Custom method If you have a unique method for synchronizing your email, you can define your own backend: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (setq +notmuch-sync-backend 'custom ;; Set this to an arbitrary shell command +notmuch-sync-command "my-notmuch-sync-cmd") -#+END_SRC +#+end_src + ** Sending mail - [[https://notmuchmail.org/notmuch-emacs/#index6h2][notmuch docs: Sending mail]] - [[https://notmuchmail.org/emacstips/#index11h2][notmuch docs: msmtp, message mode and multiple accounts]] - [[https://notmuchmail.org/emacstips/#index12h2][notmuch docs: sending mail using smtpmail]] + ** Customize =*notmuch-hello*= buffer It is possible to change the =*notmuch-hello*= buffer if you want to. - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp +;; add to $DOOMDIR/config.el (after! notmuch (setq notmuch-show-log nil notmuch-hello-sections `(notmuch-hello-insert-saved-searches notmuch-hello-insert-alltags) ;; To hide headers while composing an email notmuch-message-headers-visible nil)) -#+END_SRC +#+end_src ** Changing the =notmuch= landing page You may want to forego the =*notmuch-hello*= buffer by having ~M-x =notmuch~ or -~SPC o m~ take you straight to a search page. +[[kbd:][ o m]] take you straight to a search page. -When using ~SPC o m~ the =+notmuch-home-function= is called. By default it uses -the =notmuch= function and so has the same familiar behavior of running a +When using [[kbd:][ o m]] the ~+notmuch-home-function~ is called. By default it +uses the ~notmuch~ function and so has the same familiar behavior of running a vanilla install of notmuch-emacs. But, by overwriting this function you can run a custom search as your landing page. - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (setq +notmuch-home-function (lambda () (notmuch-search "tag:inbox"))) -#+END_SRC +#+end_src + ** Writing HTML Emails -The [[https://github.com/org-mime/org-mime][org-mime]] package provides functionality for composing emails in org-mode and transforming them to HTML. This feature is enabled using the =+org= flag. +The [[https://github.com/org-mime/org-mime][org-mime]] package provides functionality for composing emails in org-mode and +transforming them to HTML. This feature is enabled using the =+org= flag. Example use cases: +- To convert an email to an HTML email use ~M-x org-mime-htmlize~. +- To compose email using an org-mode editor buffer, use ~M-x + org-mime-edit-mail-in-org-mode~. -- To convert an email to an HTML email use ~M-x org-mime-htmlize~ -- To compose email using an org-mode editor buffer, use ~M-x org-mime-edit-mail-in-org-mode~ - -If you'd like to make configuration changes to =org-mime=, you may do so normally. By default the output of =org-mime-htmlize= includes section numbers, a byline, and a table of contents. That's probably more formal than the emails you're used to sending, so here's some example configuration that turns those features off. - -/config.el/ - +If you'd like to make configuration changes to =org-mime=, you may do so +normally. By default the output of =org-mime-htmlize= includes section numbers, +a byline, and a table of contents. That's probably more formal than the emails +you're used to sending, so here's some example configuration that turns those +features off: #+begin_src emacs-lisp +;; add to $DOOMDIR/config.el (after! org-mime (setq org-mime-export-options '(:section-numbers nil :with-author nil :with-toc nil))) #+end_src +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] -* TODO Troubleshooting +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/email/wanderlust/README.org b/modules/email/wanderlust/README.org new file mode 100644 index 000000000..37ce28fcf --- /dev/null +++ b/modules/email/wanderlust/README.org @@ -0,0 +1,55 @@ +# -*- mode: doom-docs-org -*- +#+title: :email wanderlust +#+subtitle: To boldly go where no mail has gone before +#+created: May 05, 2019 +#+since: 21.12.0 + +* Description :unfold: +#+begin_quote + πŸ”¨ This module has no description. [[doom-contrib-module:][Write one?]] +#+end_quote + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +gmail :: + Enable gmail-specific configuration for mail ~To~ or ~From~ a gmail address. + +** Packages +- [[doom-package:][wanderlust]] + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/input/README.org b/modules/input/README.org new file mode 100644 index 000000000..291a2ed52 --- /dev/null +++ b/modules/input/README.org @@ -0,0 +1,11 @@ +# -*- mode: doom-docs-org -*- +#+title: :input +#+created: May 13, 2019 +#+since: 2.0.9 + +* Description +Modules in this category extend Emacs support for additional keyboard layouts +and input methods for non-English languages. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/input/chinese/README.org b/modules/input/chinese/README.org index d2b521276..90fe99a83 100644 --- a/modules/input/chinese/README.org +++ b/modules/input/chinese/README.org @@ -1,51 +1,66 @@ -#+TITLE: input/chinese -#+DATE: May 13, 2019 -#+SINCE: 2.1 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :input chinese +#+subtitle: Spend your 3 hours a week in Emacs +#+created: May 13, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#using-fcitx5][Using fcitx5]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds support for traditional Chinese script by introducing two input methods: Pinyin and Wubi. -#+begin_quote -Because I am unable to personally test this module, help to improve this module -would be greatly appreciated! Especially where performance is concerned. -#+end_quote +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/tumashu/pyim][pyim]] (unless =+wubi=) -+ [[https://github.com/zilongshanren/chinese-wbim][chinese-wbim]] (if =+wubi=) -+ [[https://github.com/cute-jumper/fcitx.el][fcitx]] -+ [[https://github.com/cute-jumper/ace-pinyin][ace-pinyin]] -+ [[https://github.com/coldnew/pangu-spacing][pangu-spacing]] +** Packages +- [[doom-package:][ace-pinyin]] +- [[doom-package:][chinese-wbim]] if [[doom-module:][+wubi]] +- [[doom-package:][fcitx]] +- [[doom-package:][pangu-spacing]] +- [[doom-package:][pyim]] unless [[doom-module:][+wubi]] ** Hacks -+ ~org-html-paragraph~ has been modified to join consecutive Chinese lines into +- ~org-html-paragraph~ has been modified to join consecutive Chinese lines into a single long line without wanted spaced (when exporting org-mode to html). -* TODO Prerequisites -* TODO Features +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote + πŸ”¨ This module is missing install instructions. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + * TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + ** Using fcitx5 Modify ~fcitx-remote-command~ to change the default: -#+BEGIN_SRC elisp +#+begin_src emacs-lisp ;; in $DOOMDIR/config.el (setq fcitx-remote-command "fcitx5-remote") -#+END_SRC +#+end_src -* TODO Troubleshooting +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/input/japanese/README.org b/modules/input/japanese/README.org index 6eff72bac..0f960ab2c 100644 --- a/modules/input/japanese/README.org +++ b/modules/input/japanese/README.org @@ -1,43 +1,56 @@ -#+TITLE: input/japanese -#+DATE: May 13, 2019 -#+SINCE: 2.1 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :input japanese +#+subtitle: Ah, a man of culture +#+created: May 13, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds support for Japanese script. -#+begin_quote -Because I am unable to personally test this module, help to improve this module -would be greatly appreciated! Especially where performance is concerned. -#+end_quote +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/emacs-jp/migemo][migemo]] -+ [[https://github.com/momomo5717/avy-migemo][avy-migemo]] -+ [[https://github.com/hsaito/ddskk][ddskk]] -+ [[https://github.com/coldnew/pangu-spacing][pangu-spacing]] +** Packages +- [[doom-package:][avy-migemo]] +- [[doom-package:][ddskk]] +- [[doom-package:][migemo]] +- [[doom-package:][pangu-spacing]] ** Hacks -+ ~org-html-paragraph~ has been modified to join consecutive Chinese lines into +- ~org-html-paragraph~ has been modified to join consecutive Chinese lines into a single long line without wanted spaced (when exporting org-mode to html). -* TODO Prerequisites -+ For incremental search with Migemo, one of the following is required: - + [[https://github.com/koron/cmigemo][cmigemo]], which is recommended, or - + [[http://0xcc.net/migemo/][CVS Head Migemo]] -* TODO Features +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +- For incremental search with Migemo, one of the following is required: + - [[https://github.com/koron/cmigemo][cmigemo]] (recommended) + - or [[http://0xcc.net/migemo/][CVS Head Migemo]] + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + * TODO Configuration -* TODO Troubleshooting +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/input/layout/README.org b/modules/input/layout/README.org index 11da4b928..d50b4d277 100644 --- a/modules/input/layout/README.org +++ b/modules/input/layout/README.org @@ -1,140 +1,139 @@ -#+TITLE: input/layout -#+DATE: Jun 29, 2020 -#+SINCE: v3.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :input layout +#+subtitle: auie,ctsrnm is the superior home row +#+created: Jun 29, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#bΓ©po][BΓ©po]] - - [[#easymotion][Easymotion]] - - [[#leaving-mnemonics-alone-when-possible][Leaving mnemonics alone when possible]] - - [[#possible-contributions][Possible contributions]] - - [[#org-mode][Org-mode]] -- [[#configuration][Configuration]] - - [[#bΓ©po-1][BΓ©po]] -- [[#troubleshooting][Troubleshooting]] - - [[#outstanding-issues-contributions-welcome][Outstanding issues (contributions welcome)]] - - [[#bΓ©po-2][BΓ©po]] - - [[#how-to-investigate-an-issue-][How to investigate an issue ?]] - - [[#how-to-deactivate-the-new-bindings-and-go-back-to-the-old-ones-][How to deactivate the new bindings and go back to the old ones ?]] - -* Description -This module provides barebones support for using Doom with non-qwerty layouts. +* Description :unfold: +This module provides barebones support for using Doom with non-qwerty keyboard +layouts. ** Maintainers -+ @gagbo (Author, BΓ©po) +- [[doom-user:][@gagbo]] ([[kbd:][+bepo]]) -** Module Flags -+ =+azerty= Remaps keybinds to accommodate the - [[https://en.wikipedia.org/wiki/AZERTY][Azerty keyboard layout]]. -+ =+bepo= Remaps keybinds to accommodate the - [[https://en.wikipedia.org/wiki/B%C3%89PO][BΓ‰PO keyboard layout]] (version - 1.1, in particualr). +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -None +** Module flags +- +azerty :: + Remap keybinds to accommodate the [[https://en.wikipedia.org/wiki/AZERTY][Azerty keyboard layout]]. +- +bepo :: + Remap keybinds to accommodate the [[https://en.wikipedia.org/wiki/B%C3%89PO][BΓ‰PO keyboard layout]] (version 1.1, in + particular). -* Prerequisites -If you are using =:editor evil=, you should use =(evil +everywhere)=, as the -module uses =evil-collection= utilities to do the remapping. +** Packages +/This module doesn't install any packages./ -If you are not using =:editor evil=, then you have nothing to do. +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features -# An in-depth list of features, how to use them, and their dependencies. ** BΓ©po Support for the bΓ©po layout includes: - Setting Avy keys to the correct home row keys -- Changing navigation keys to =ctsr= - + old =t= is mapped to =j= - + old =s= is mapped to =k= (i.e. staging in the magit status buffer is done - with =k=) - + See [[*Configuration][Configuration]] to see where old =c= and =r= functions +- Changing navigation keys to [[kbd:][c]], [[kbd:][t]], [[kbd:][s]], and [[kbd:][r]] + + old [[kbd:][t]] is mapped to [[kbd:][j]] + + old [[kbd:][s]] is mapped to [[kbd:][k]] (i.e. staging in the magit status buffer is done with + [[kbd:][k]]) + + See [[*Configuration][Configuration]] to see where old [[kbd:][c]] and [[kbd:][r]] functions are remapped -- Bind =<>= functions to =«»= keys when possible -- Bind =[]= functions to =()= keys when possible (the "unimpaired-like" - bindings) -- Bind =Γ©= key to =w= functions when possible -- Bind =Γ¨= key to useful functions when possible -- Bind =`~= functions to =$#= keys when possible +- Bind [[kbd:][<>]] functions to [[kbd:][«»]] keys when possible +- Bind [[kbd:][[]]] functions to [[kbd:][()]] keys when possible (the "unimpaired-like" bindings) +- Bind [[kbd:][Γ©]] key to [[kbd:][w]] functions when possible +- Bind [[kbd:][Γ¨]] key to useful functions when possible +- Bind [[kbd:][`~]] functions to [[kbd:][$#]] keys when possible *** Easymotion -If you use =evil-easymotion=, then all the bindings that were on =gs= have been -moved to =gΓ©=. +If you use [[doom-package:][evil-easymotion]], then all the bindings that were on [[kbd:][gs]] have been +moved to [[kbd:][gΓ©]]. -In short : =g s j= -> =g Γ© t= (evilem-motion-next-line). And so on. +In short : [[kbd:][g s j]] -> [[kbd:][g Γ© t]] (~evilem-motion-next-line~). And so on. *** Leaving mnemonics alone when possible -Exchanging =hjkl= to =ctsr= has the effect of destroying a few mnemonics: the -change operator becomes =l= for example, or the window split becomes =SPC Γ© k=. +Exchanging [[kbd:][h]]/[[kbd:][j]]/[[kbd:][k]]/[[kbd:][l]] to [[kbd:][c]]/[[kbd:][t]]/[[kbd:][s]]/[[kbd:][r]] has the effect of destroying a few mnemonics: the +change operator becomes [[kbd:][l]] for example, or the window split becomes [[kbd:][SPC Γ© k]]. The module tries to limit those changes to the minimum, especially in special buffers. A concrete example is magit. -As the =magit: project= buffer (obtained with =magit-status=) does not need -left-right navigation, keys =c=, =r=, =h=, and =l= keep their "expected" bindings, -while =t=, =s=, =j=, and =k= are flipped: -- checking the log from a magit buffer is still on =l= -- staging a file/region has been moved to =k= +As the =magit: project= buffer (obtained with ~M-x magit-status~) does not need +left-right navigation, keys [[kbd:][c]], [[kbd:][r]], [[kbd:][h]], and [[kbd:][l]] keep their "expected" bindings, while +[[kbd:][t]], [[kbd:][s]], [[kbd:][j]], and [[kbd:][k]] are flipped: +- checking the log from a magit buffer is still on [[kbd:][l]] +- staging a file/region has been moved to [[kbd:][k]] *** Possible contributions -**** Avoid =g= and =z= to be used too often +**** Avoid [[kbd:][g]] and [[kbd:][z]] to be used too often A nice addition in the future might be to have all the normal mode bindings that -start with =g= start with =,= instead to avoid the curl on these common -bindings. This is *not* implemented for the time being. +start with [[kbd:][g]] start with [[kbd:][,]] instead to avoid the curl on these common bindings. +This is *not* implemented for the time being. -The same thing could be done to =z=, potentially using =Γ = instead. +The same thing could be done to [[kbd:][z]], potentially using [[kbd:][Γ ]] instead. **** Proper minor mode Also, implementing all those changes as a minor we could flip on and off would help with adoption **** Put "word" text objects to Γ© instead of w -"inside word" and "around word" are =iw= and =aw=, which use the very poorly -rated =w= key in the bΓ©po layout. Finding a way to use =Γ©= or even =Γ¨= more for -these would be a welcome change +"inside word" and "around word" are [[kbd:][iw]] and [[kbd:][aw]], which use the very poorly rated [[kbd:][w]] +key in the bΓ©po layout. Finding a way to use [[kbd:][Γ©]] or even [[kbd:][Γ¨]] more for these would be +a welcome change *** Org-mode -=evil-org= allows to define =evil-org-movement-bindings= to automatically map -movement bindings on non-hjkl keys. It maps automatically keys to =C-c= and -=C-r= in normal and insert states though, and it's not really user friendly in -Emacs to remap those. +[[doom-package:][evil-org]] allows to define ~evil-org-movement-bindings~ to automatically map +movement bindings on non-hjkl keys. It maps automatically keys to [[kbd:][C-c]] and [[kbd:][C-r]] in +normal and insert states though, and it's not really user friendly in Emacs to +remap those. -Therefore, in org-mode: -- =org-shiftright= is bound to =C-Β»= -- =org-shiftleft= is bound to =C-Β«= +Therefore, in ~org-mode~: +- ~org-shiftright~ is bound to [[kbd:][C-Β»]] +- ~org-shiftleft~ is bound to [[kbd:][C-Β«]] + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** BΓ©po =+layout-bepo-cr-rotation-style= controls whether: - =qwerty-c= functions are mapped on =bΓ©po-l= key, and =qwerty-r= functions on - =bΓ©po-h= key (='ergodis=), or + =bΓ©po-h= key (~'ergodis~), or - =qwerty-c= functions are mapped on =bΓ©po-h= key, and =qwerty-r= functions on - =bΓ©po-l= key (='strict=) + =bΓ©po-l= key (~'strict~) -='strict= would be the logical choice but the =c= functions are used more often -than the =r= ones so [[https://bepo.fr/wiki/Vim#Principe][Ergodis]] advises to actually put all the =c= functions on -the key that does not need a curl. +~'strict~ would be the logical choice but the [[kbd:][c]] functions are used more often +than the [[kbd:][r]] ones so [[https://bepo.fr/wiki/Vim#Principe][Ergodis]] advises to actually put all the [[kbd:][c]] functions on the +key that does not need a curl. * Troubleshooting -# Common issues and their solution, or places to look for help. +[[doom-report:][Report an issue?]] + ** Outstanding issues (contributions welcome) *** BΓ©po -- in eshell, the key `c` is still bound to - `evil-collection-eshell-evil-change` in normal mode +- In [[doom-package:][eshell]], the key [[kbd:][c]] is still bound to ~evil-collection-eshell-evil-change~ in + normal mode. ** How to investigate an issue ? -If a key is misbehaving, use =describe-key= (=C-h k= or =SPC h k= or =F1 k=) to -see the functions bound to the key, and more importantly in which map it is +If a key is misbehaving, use ~M-x describe-key~ ([[kbd:][C-h k]] or [[kbd:][SPC h k]] or [[kbd:][F1 k]]) to +see the command bound to the key, and more importantly in which keymap it is bound. -You should ignore all =evil-collection-...-backup-map= keymaps, as they are -artifacts from =evil-collection-translate-key= and those maps are actually not +You should ignore all ~evil-collection-*-backup-map~ keymaps, as they are +artifacts from ~evil-collection-translate-key~ and those maps are actually not active. Most likely the solution is to call one of the "key rotation" functions on the @@ -142,8 +141,16 @@ relevant keymaps. ** How to deactivate the new bindings and go back to the old ones ? If you are learning a new layout you might want to go back to tho old one to -"get work done". Sadly the only way is to comment out the module, run =doom -sync= and restart emacs. +"get work done". Sadly the only way is to comment out the module, run ~$ doom +sync~ and restart emacs. -Restoring the session =SPC q l= by default helps to lower the impact of the +Restoring the session [[kbd:][SPC q l]] by default helps to lower the impact of the restart. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/README.org b/modules/lang/README.org new file mode 100644 index 000000000..0b87362d4 --- /dev/null +++ b/modules/lang/README.org @@ -0,0 +1,11 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang +#+created: August 03, 2021 +#+since: 21.12.0 + +* Description +These modules specialize in integration particular languages and their +ecosystems into (Doom) Emacs. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/lang/agda/README.org b/modules/lang/agda/README.org index 6713085bf..e9e5cca84 100644 --- a/modules/lang/agda/README.org +++ b/modules/lang/agda/README.org @@ -1,4 +1,57 @@ -#+TITLE: :lang agda +# -*- mode: doom-docs-org -*- +#+title: :lang agda +#+subtitle: Types of types of types of types... +#+created: August 21, 2018 +#+since: 21.12.0 (#821) +* Description :unfold: This module adds support for the [[http://wiki.portal.chalmers.se/agda/pmwiki.php][agda]] programming language. The Emacs support -exists directly in the agda repository but not in melpa. +exists directly in the agda repository, but not in melpa. + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +local :: + Use the =agda-mode= executable that comes with your local =agda= install. +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. + +** Packages +- unless [[doom-module:][+local]] + - [[doom-package:][agda-input]] + - [[doom-package:][agda2-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/beancount/README.org b/modules/lang/beancount/README.org index e958e5950..5af5a19ca 100644 --- a/modules/lang/beancount/README.org +++ b/modules/lang/beancount/README.org @@ -1,53 +1,58 @@ -#+TITLE: lang/beancount -#+DATE: April 13, 2021 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang beancount +#+subtitle: Mind the GAAP +#+created: April 13, 2021 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds support for [[https://beancount.github.io/][Beancount]] to Emacs. Beancount, like ledger, lets you [[https://plaintextaccounting.org/][manage your money in plain text]]. -+ Supports [[https://github.com/polarmutex/beancount-language-server][beancount-language-server]] (if module is enabled with the =+lsp= - flag). - ** Maintainers -This module has no dedicated maintainers. +- @hlissner -** Module Flags -+ =+lsp= Enable support for [beancount-language-server]. Requires Doom's =:tools - lsp= module. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/beancount/beancount-mode][beancount]] +** Module flags +- +lsp :: + Enable LSP support for ~beancount-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/polarmutex/beancount-language-server][beancount-language-server]]). + +** Packages +- [[doom-package:][beancount]] ** Hacks -+ Associates the material =attach_money= icon with *.beancount files in the - =all-the-icons= package. +- Associates the material =attach_money= icon with =*.beancount= files in the + [[doom-package:][all-the-icons]] package. -* Prerequisites -This module has no hard prerequisites, but assumes you have [[https://github.com/beancount/beancount][beancount]] installed -in order to generate reports with ~bean-report~. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- [[https://github.com/beancount/beancount][beancount]], for generating reports +- [[https://beancount.github.io/fava/][fava]], for a web interface for your ledgers + +* TODO Usage #+begin_quote -Also: the ~beancount-fava~ command requires [[https://beancount.github.io/fava/][fava]]. + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] #+end_quote -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. - * TODO Configuration -# How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/cc/README.org b/modules/lang/cc/README.org index 3244861aa..955e4eb19 100644 --- a/modules/lang/cc/README.org +++ b/modules/lang/cc/README.org @@ -1,73 +1,73 @@ -#+TITLE: lang/cc -#+DATE: January 16, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang cc +#+subtitle: C > C++ == 1 +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#lsp-servers][LSP servers]] - - [[#irony-server][irony-server]] - - [[#macos][macOS]] - - [[#rtags][rtags]] -- [[#configure][Configure]] - - [[#project-compile-settings][Project compile settings]] - - [[#known-issues-with-bear-on-macos][Known issues with bear on macOS]] - - [[#configure-lsp-servers][Configure LSP servers]] - - [[#lsp-mode-with-clangd][LSP-mode with clangd]] - - [[#lsp-mode-with-ccls][LSP-mode with ccls]] - - [[#eglot-with-clangd][Eglot with clangd]] - - [[#eglot-with-ccls][Eglot with ccls]] -- [[#appendix][Appendix]] - - [[#eglot-specific-bindings][Eglot specific bindings]] - -* Description +* Description :unfold: This module adds support for the C-family of languages: C, C++, and Objective-C. -+ Code completion (~company-irony~) -+ eldoc support (~irony-eldoc~) -+ Syntax-checking (~flycheck-irony~) -+ Code navigation (~rtags~) -+ File Templates ([[../../editor/file-templates/templates/c-mode][c-mode]], [[../../editor/file-templates/templates/c++-mode][c++-mode]]) -+ Snippets ([[https://github.com/hlissner/doom-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c++-mode][c++-mode]]) -+ Several improvements to C++11 indentation and syntax highlighting. +- Code completion (~company-irony~) +- eldoc support (~irony-eldoc~) +- Syntax-checking (~flycheck-irony~) +- Code navigation (~rtags~) +- File Templates ([[../../editor/file-templates/templates/c-mode][c-mode]], [[../../editor/file-templates/templates/c++-mode][c++-mode]]) +- Snippets ([[https://github.com/hlissner/doom-snippets/tree/master/cc-mode][cc-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c-mode][c-mode]], [[https://github.com/hlissner/doom-snippets/tree/master/c++-mode][c++-mode]]) +- Several improvements to C++11 indentation and syntax highlighting. -** Module Flags -+ ~+lsp~ Disables irony+rtags and replaces them with LSP (ccls by default). This - requires the =:tools lsp= module. +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ [[https://github.com/Kitware/CMake][cmake-mode]] -+ [[https://github.com/chachi/cuda-mode][cuda-mode]] -+ [[https://github.com/liblit/demangle-mode][demangle-mode]] -+ [[https://github.com/jart/disaster][disaster]] -+ [[https://github.com/ludwigpacifici/modern-cpp-font-lock][modern-cpp-font-lock]] -+ [[https://github.com/salmanebah/opencl-mode][opencl-mode]] -+ [[https://github.com/jimhourihan/glsl-mode][glsl-mode]]* -+ [[https://github.com/guidoschmidt/company-glsl][company-glsl]]* -+ =+lsp= - + [[https://github.com/MaskRay/emacs-ccls][ccls]] if =:tools lsp= has *no* =+eglot= flag -+ =-lsp= - + [[https://github.com/Sarcasm/irony-mode][irony]] - + [[https://github.com/ikirill/irony-eldoc][irony-eldoc]] - + [[https://github.com/Sarcasm/flycheck-irony][flycheck-irony]] - + [[https://github.com/Sarcasm/company-irony][company-irony]] - + [[https://github.com/hotpxl/company-irony-c-headers][company-irony-c-headers]] - + [[https://github.com/Andersbakken/rtags][rtags]] - + [[https://github.com/Andersbakken/rtags][ivy-rtags]] - + [[https://github.com/Andersbakken/rtags][helm-rtags]] +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~c-mode~, ~c++-mode~, and ~objc-mode~. Requires [[doom-module:][:tools + lsp]] and a langserver (supports ccls, clangd, and cquery). Replaces irony & + rtags. +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. + +** Packages +- [[doom-package:][cmake-mode]] +- [[doom-package:][company-glsl]] +- [[doom-package:][cuda-mode]] +- [[doom-package:][demangle-mode]] +- [[doom-package:][disaster]] +- [[doom-package:][glsl-mode]] +- [[doom-package:][modern-cpp-font-lock]] +- [[doom-package:][opencl-mode]] +- if [[doom-module:][+lsp]] + - [[doom-package:][ccls]] if [[doom-module:][:tools lsp -eglot]] +- else + - [[doom-package:][company-irony]] + - [[doom-package:][company-irony-c-headers]] + - [[doom-package:][flycheck-irony]] + - [[doom-package:][helm-rtags]] if [[doom-module:][:completion helm]] + - [[doom-package:][irony]] + - [[doom-package:][irony-eldoc]] + - [[doom-package:][ivy-rtags]] if [[doom-module:][:completion ivy]] + - [[doom-package:][rtags]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites This module's requirements change depending on how you use it. -+ If =+lsp= is enabled, you need one of *clangd v9+* or *ccls*. -+ If =+lsp= is *not* enabled, you need *irony-server* and *rtags*. -+ Other features in this module depend on: - + (optional) glslangValidator, for GLSL completion in ~glsl-mode~ - + (optional) cmake, for code completion in ~cmake-mode~ -+ You will need a C/C++ compiler, like =gcc= or =clang=. +- If [[doom-module:][+lsp]] is enabled, you need one of *clangd v9+* or *ccls*. +- If [[doom-module:][+lsp]] is *not* enabled, you need *irony-server* and *rtags*. +- Other features in this module depend on: + - (optional) glslangValidator, for GLSL completion in ~glsl-mode~ + - (optional) cmake, for code completion in ~cmake-mode~ +- You will need a C/C++ compiler, like =gcc= or =clang=. ** LSP servers =lsp-mode= and =eglot= support a few LSP servers, but =clangd= and =ccls= are @@ -76,13 +76,13 @@ recommended. + clangd (must be v9 or newer) :: clangd is included with =llvm= which should be available through your OS' package manager. - Linux: - - Debian 11 & Ubuntu 20.10: ~# apt-get install clangd-11~ + - Debian 11 & Ubuntu 20.10: ~$ apt-get install clangd-11~ - 20.04 LTS: [[https://pkgs.org/search/?q=clangd][clangd-10]] - - Fedora & CentOS/RHEL 8+: ~# dnf install clang-tools-extra~ - - openSUSE: ~# zypper install clang~ - - Arch: ~# pacman -S clang~ + - Fedora & CentOS/RHEL 8+: ~$ dnf install clang-tools-extra~ + - openSUSE: ~$ zypper install clang~ + - Arch: ~$ pacman -S clang~ - BSDs: - - NetBSD & OpenBSD: ~# pkg_add clang-tools-extra~ + - NetBSD & OpenBSD: ~$ pkg_add clang-tools-extra~ - macOS: ~$ brew install llvm~ // 1GB+ installation! May take a while! - Windows: use the win64 installer from [[https://releases.llvm.org/download.html][LLVM's GitHub release page]]. + ccls :: Available in many OS' package managers as =ccls=. Otherwise, there are @@ -97,14 +97,13 @@ irony-install-server~ in Emacs. *** macOS Due to linking issues, macOS users must compile irony-server manually: - -#+BEGIN_SRC sh +#+begin_src sh brew install cmake brew install llvm git clone https://github.com/Sarcasm/irony-mode irony-mode -#+END_SRC +#+end_src -#+BEGIN_SRC bash +#+begin_src sh mkdir irony-mode/server/build pushd irony-mode/server/build @@ -121,7 +120,7 @@ install_name_tool -change @rpath/libclang.dylib \ # Cleanup popd rm -rf irony-mode -#+END_SRC +#+end_src ** rtags Code navigation requires an [[https://github.com/Andersbakken/rtags][rtags]] server (~rdm~) installed. This should be @@ -130,12 +129,36 @@ available through your OS's package manager. This module will auto-start ~rdm~ when you open C/C++ buffers (so long as one isn't already running). If you prefer to run it yourself: -#+BEGIN_SRC sh +#+begin_src sh rdm & rc -J $PROJECT_ROOT # loads PROJECT_ROOT's compile_commands.json -#+END_SRC +#+end_src + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +1. Enable this module. +2. Enable the ~+lsp~ flag for the appropriate modules you want LSP support for + (e.g. ~:lang (python +lsp)~ or ~:lang (rust +lsp)~), +3. Install the prerequisite LSP servers through your package manager or other + means. You can find a list of supported servers on [[https://github.com/emacs-lsp/lsp-mode#supported-languages][the lsp-mode project page]]. +4. Run ~$ doom sync~ on the command line and restart Emacs. + +** Eglot-specific bindings +When using [[doom-module:][+lsp]] and [[doom-module:][:tools lsp +eglot]], [[doom-package:][lsp-mode]] is replaced with [[doom-package:][eglot]], and an +additional function to get inheritance type hierarchy is added: +| Binding | Description | +|----------------------------+------------------------------------------------| +| [[kbd:][ c t]] | Display inheritance type hierarchy (upwards) | +| [[kbd:][ c t]] | Display inheritance type hierarchy (downwards) | + +* TODO Configure +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configure ** Project compile settings By default, a set of default compile settings are defined in ~+cc-default-compiler-options~ for C, C++ and Objective C. Irony, rtags and @@ -145,16 +168,16 @@ For a more universal solution: both LSP servers and irony will recognize a [[https://sarcasm.github.io/notes/dev/compilation-database.html#ninja][compilation database]] (a ~compile_commands.json~ file). There are [[https://sarcasm.github.io/notes/dev/compilation-database.html][many ways to generate one]]. Here is an example using [[http://www.cmake.org/][CMake]] and [[https://github.com/rizsotto/Bear][bear]]: -#+BEGIN_SRC sh +#+begin_src sh # For CMake projects cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=ON . -#+END_SRC +#+end_src -#+BEGIN_SRC sh +#+begin_src sh # For non-CMake projects make clean bear make -#+END_SRC +#+end_src Use ~M-x +cc/reload-compile-db~ to reload your compile db in an already-open C/C++/ObjC buffer. @@ -164,7 +187,6 @@ MacOS' [[https://support.apple.com/en-us/HT204899][System Integrity Protection ( under ~/usr/bin/~ which results in an empty compilation database. From the bear [[https://github.com/rizsotto/Bear#empty-compilation-database-on-os-x-captain-or-fedora][readme]]: - #+begin_quote Security extension/modes on different operating systems might disable library preloads. This case Bear behaves normally, but the result compilation database @@ -182,77 +204,76 @@ such tool might be scan-build. The build system shall respect CC and CXX environment variables. #+end_quote -A workaround might be to install ~make~ via Homebrew which puts ~gmake~ -under ~/usr/local/~. - -#+BEGIN_SRC sh +A workaround might be to install ~make~ via Homebrew which puts ~gmake~ under +=/usr/local/=: +#+begin_src sh brew install make -#+END_SRC - -#+BEGIN_SRC sh +#+end_src +#+begin_src sh make clean bear gmake -#+END_SRC +#+end_src Additional info: -+ [[https://github.com/rizsotto/Bear/issues/158][Empty compilation database with compiler in /usr/local]] -+ [[https://github.com/rizsotto/Bear/issues/152][Workaround for 'Empty compilation database on OS X Captain]] +- [[https://github.com/rizsotto/Bear/issues/158][Empty compilation database with compiler in /usr/local]] +- [[https://github.com/rizsotto/Bear/issues/152][Workaround for 'Empty compilation database on OS X Captain]] ** Configure LSP servers Search for your combination of =(LSP client package, LSP server)=. You are using -=LSP-mode= by default, =eglot= if you have =:tools (lsp +eglot)= active in your -=init.el= file. +[[doom-package:][lsp-mode]] by default, [[doom-package:][eglot]] if you have [[doom-module:][:tools lsp +eglot]] active in +=$DOOMDIR/init.el= file. *** LSP-mode with clangd +#+begin_src emacs-lisp +(after! lsp-clangd + (setq lsp-clients-clangd-args + '("-j=3" + "--background-index" + "--clang-tidy" + "--completion-style=detailed" + "--header-insertion=never" + "--header-insertion-decorators=0")) + (set-lsp-priority! 'clangd 2)) +#+end_src -#+BEGIN_SRC elisp -(setq lsp-clients-clangd-args '("-j=3" - "--background-index" - "--clang-tidy" - "--completion-style=detailed" - "--header-insertion=never" - "--header-insertion-decorators=0")) -(after! lsp-clangd (set-lsp-priority! 'clangd 2)) -#+END_SRC - -This will both set your clangd flags and choose =clangd= as the default LSP server everywhere clangd can be used. +This will both set your clangd flags and choose =clangd= as the default LSP +server everywhere clangd can be used. *** LSP-mode with ccls - -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (after! ccls (setq ccls-initialization-options '(:index (:comments 2) :completion (:detailedLabel t))) (set-lsp-priority! 'ccls 2)) ; optional as ccls is the default in Doom -#+END_SRC +#+end_src This will both set your ccls flags and choose ccls as the default server. [[https://github.com/MaskRay/ccls/wiki/Customization#--initjson][CCLS documentation]] lists available options, use =t= for ~true~, =:json-false= for ~false~, and =:json-null= for ~null~. *** Eglot with clangd - -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (set-eglot-client! 'cc-mode '("clangd" "-j=3" "--clang-tidy")) -#+END_SRC +#+end_src This will both set your clangd flags and choose clangd as the default server (if it is the last =set-eglot-client! 'cc-mode= in your config). *** Eglot with ccls - -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (set-eglot-client! 'cc-mode '("ccls" "--init={\"index\": {\"threads\": 3}}")) -#+END_SRC +#+end_src This will both set your ccls flags and choose ccls as the default server (if it is the last =set-eglot-client! 'cc-mode= in your config). [[https://github.com/MaskRay/ccls/wiki/Customization#--initjson][CCLS documentation]] lists available options -* Appendix -** Eglot specific bindings -When using =+lsp= and =:tools (lsp +eglot)=, lsp-mode is replaced with eglot, -and an additional function to get inheritance type hierarchy is added -| Binding | Description | -|------------------------------+--------------------------------------------------| -| ~ c t~ | ~Display inheritance type hierarchy (upwards)~ | -| ~ c t~ | ~Display inheritance type hierarchy (downwards)~ | +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/clojure/README.org b/modules/lang/clojure/README.org index 60ea2cfd8..44cda9825 100644 --- a/modules/lang/clojure/README.org +++ b/modules/lang/clojure/README.org @@ -1,115 +1,121 @@ -#+TITLE: lang/clojure -#+DATE: May 30, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang clojure +#+subtitle: Java with a lisp +#+created: May 30, 2017 +#+since: 2.0.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#keybindings][Keybindings]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds support for the Clojure(Script) language. -+ Interactive development environment (~cider~): REPL, compilation, debugging, +- Interactive development environment (~cider~): REPL, compilation, debugging, running tests, definitions & documentation lookup, code completion, and much more -+ Refactoring (~clj-refactor~) -+ Linting (~clj-kondo~), requires ~:checkers syntax~ -+ LSP support (~clojure-lsp~) +- Refactoring (~clj-refactor~) +- Linting (~clj-kondo~), requires ~:checkers syntax~ +- LSP support (~clojure-lsp~) ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+lsp= Enables LSP support, alongside Cider. +** Module flags +- +lsp :: + Enable LSP support for ~clojure-mode~ (alongside Cider). Requires [[doom-module:][:tools lsp]] + and a langserver (supports [[https://clojure-lsp.io/][clojure-lsp]]). -** Plugins -+ [[https://github.com/clojure-emacs/cider][cider]] -+ [[https://github.com/clojure-emacs/clj-refactor.el][clj-refactor]] -+ [[https://github.com/borkdude/flycheck-clj-kondo][flycheck-clj-kondo]] +** Packages +- [[doom-package:][cider]] +- [[doom-package:][clj-refactor]] +- [[doom-package:][flycheck-clj-kondo]] if [[doom-module:][:checkers syntax]] ** Hacks -+ Error messages emitted from CIDER are piped into the REPL buffer when it is +- Error messages emitted from CIDER are piped into the REPL buffer when it is first opened, to make them easier to notice. -+ Disabled the help banner when opening the cider REPL. +- Disabled the help banner when opening the cider REPL. + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites This module requires: +- [[https://clojure.org/][clojure]] +- [[https://leiningen.org/][leiningen]], for the REPL +- [[https://github.com/borkdude/clj-kondo][clj-kondo]], for linting code +- [[https://clojure-lsp.github.io/clojure-lsp/][clojure-lsp]], for LSP support (if [[doom-module:][+lsp]]) -+ [[https://clojure.org/][clojure]] -+ [[https://leiningen.org/][leiningen]] (REPL) -+ [[https://github.com/borkdude/clj-kondo][clj-kondo]] (linter) -+ With =+lsp= - + [[https://clojure-lsp.github.io/clojure-lsp/][clojure-lsp]] +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote - -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. -** Keybindings -| Binding | Description | -|---------------------+------------------------------------------------------| -| = '​= | =cider-jack-in-clj= | -| = C= | =cider-connect-cljs= | -| = M= | =cider-macroexpand-all= | -| = R= | =hydra-cljr-help-menu/body= | -| = c= | =cider-connect-clj= | -| = e D= | =cider-insert-defun-in-repl= | -| = e E= | =cider-insert-last-sexp-in-repl= | -| = e R= | =cider-insert-region-in-repl= | -| = e b= | =cider-eval-buffer= | -| = e d= | =cider-eval-defun-at-point= | -| = e e= | =cider-eval-last-sexp= | -| = e r= | =cider-eval-region= | -| = e u= | =cider-undef= | -| = g b= | =cider-pop-back= | -| = g g= | =cider-find-var= | -| = g n= | =cider-find-ns= | -| = h a= | =cider-apropos= | -| = h c= | =cider-clojuredocs= | -| = h d= | =cider-doc= | -| = h j= | =cider-javadoc= | -| = h n= | =cider-find-ns= | -| = h w= | =cider-clojuredocs-web= | -| = i e= | =cider-enlighten-mode= | -| = i i= | =cider-inspect= | -| = i r= | =cider-inspect-last-result= | -| = m "​= | =cider-jack-in-cljs= | -| = m= | =cider-macroexpand-1= | -| = n N= | =cider-browse-ns-all= | -| = n n= | =cider-browse-ns= | -| = n r= | =cider-ns-refresh= | -| = p d= | =cider-pprint-eval-defun-at-point= | -| = p D= | =cider-pprint-eval-defun-to-comment= | -| = p p= | =cider-pprint-eval-last-sexp= | -| = p P= | =cider-pprint-eval-last-sexp-to-comment= | -| = p r= | =cider-pprint-eval-last-sexp-to-repl= | -| = r B= | =+clojure/cider-switch-to-repl-buffer-and-switch-ns= | -| = r L= | =cider-load-buffer-and-switch-to-repl-buffer= | -| = r R= | =cider-restart= | -| = r b= | =cider-switch-to-repl-buffer= | -| = r c= | =cider-find-and-clear-repl-output= | -| = r l= | =cider-load-buffer= | -| = r n= | =cider-repl-set-ns= | -| = r q= | =cider-quit= | -| = r r= | =cider-ns-refresh= | -| = t a= | =cider-test-rerun-test= | -| = t l= | =cider-test-run-loaded-tests= | -| = t n= | =cider-test-run-ns-tests= | -| = t p= | =cider-test-run-project-tests= | -| = t r= | =cider-test-rerun-failed-tests= | -| = t s= | =cider-test-run-ns-tests-with-filters= | -| = t t= | =cider-test-run-test= | +| Keybind | Command | +|-------------------+------------------------------------------------------| +| [[kbd:][ ']] | ~cider-jack-in-clj~ | +| [[kbd:][ C]] | ~cider-connect-cljs~ | +| [[kbd:][ M]] | ~cider-macroexpand-all~ | +| [[kbd:][ R]] | ~hydra-cljr-help-menu/body~ | +| [[kbd:][ c]] | ~cider-connect-clj~ | +| [[kbd:][ e D]] | ~cider-insert-defun-in-repl~ | +| [[kbd:][ e E]] | ~cider-insert-last-sexp-in-repl~ | +| [[kbd:][ e R]] | ~cider-insert-region-in-repl~ | +| [[kbd:][ e b]] | ~cider-eval-buffer~ | +| [[kbd:][ e d]] | ~cider-eval-defun-at-point~ | +| [[kbd:][ e e]] | ~cider-eval-last-sexp~ | +| [[kbd:][ e r]] | ~cider-eval-region~ | +| [[kbd:][ e u]] | ~cider-undef~ | +| [[kbd:][ g b]] | ~cider-pop-back~ | +| [[kbd:][ g g]] | ~cider-find-var~ | +| [[kbd:][ g n]] | ~cider-find-ns~ | +| [[kbd:][ h a]] | ~cider-apropos~ | +| [[kbd:][ h c]] | ~cider-clojuredocs~ | +| [[kbd:][ h d]] | ~cider-doc~ | +| [[kbd:][ h j]] | ~cider-javadoc~ | +| [[kbd:][ h n]] | ~cider-find-ns~ | +| [[kbd:][ h w]] | ~cider-clojuredocs-web~ | +| [[kbd:][ i e]] | ~cider-enlighten-mode~ | +| [[kbd:][ i i]] | ~cider-inspect~ | +| [[kbd:][ i r]] | ~cider-inspect-last-result~ | +| [[kbd:][ m "]] | ~cider-jack-in-cljs~ | +| [[kbd:][ m]] | ~cider-macroexpand-1~ | +| [[kbd:][ n N]] | ~cider-browse-ns-all~ | +| [[kbd:][ n n]] | ~cider-browse-ns~ | +| [[kbd:][ n r]] | ~cider-ns-refresh~ | +| [[kbd:][ p d]] | ~cider-pprint-eval-defun-at-point~ | +| [[kbd:][ p D]] | ~cider-pprint-eval-defun-to-comment~ | +| [[kbd:][ p p]] | ~cider-pprint-eval-last-sexp~ | +| [[kbd:][ p P]] | ~cider-pprint-eval-last-sexp-to-comment~ | +| [[kbd:][ p r]] | ~cider-pprint-eval-last-sexp-to-repl~ | +| [[kbd:][ r B]] | ~+clojure/cider-switch-to-repl-buffer-and-switch-ns~ | +| [[kbd:][ r L]] | ~cider-load-buffer-and-switch-to-repl-buffer~ | +| [[kbd:][ r R]] | ~cider-restart~ | +| [[kbd:][ r b]] | ~cider-switch-to-repl-buffer~ | +| [[kbd:][ r c]] | ~cider-find-and-clear-repl-output~ | +| [[kbd:][ r l]] | ~cider-load-buffer~ | +| [[kbd:][ r n]] | ~cider-repl-set-ns~ | +| [[kbd:][ r q]] | ~cider-quit~ | +| [[kbd:][ r r]] | ~cider-ns-refresh~ | +| [[kbd:][ t a]] | ~cider-test-rerun-test~ | +| [[kbd:][ t l]] | ~cider-test-run-loaded-tests~ | +| [[kbd:][ t n]] | ~cider-test-run-ns-tests~ | +| [[kbd:][ t p]] | ~cider-test-run-project-tests~ | +| [[kbd:][ t r]] | ~cider-test-rerun-failed-tests~ | +| [[kbd:][ t s]] | ~cider-test-run-ns-tests-with-filters~ | +| [[kbd:][ t t]] | ~cider-test-run-test~ | * TODO Configuration -# How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/common-lisp/README.org b/modules/lang/common-lisp/README.org index d9043c21d..879de0f88 100644 --- a/modules/lang/common-lisp/README.org +++ b/modules/lang/common-lisp/README.org @@ -1,22 +1,11 @@ -#+TITLE: lang/common-lisp -#+DATE: June 13, 2018 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang common-lisp +#+subtitle: If you've seen one lisp, you've seen them all +#+created: June 13, 2018 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#sly][Sly]] - - [[#org-mode][org-mode]] -- [[#configuration][Configuration]] - -* Description - -This module provides support for [[https://lisp-lang.org/][Common Lisp]] and the [[https://github.com/joaotavora/sly][Sly]] development +* Description :unfold: +This module provides support for [[https://lisp-lang.org/][Common Lisp]] and the [[doom-package:][Sly]] development environment. Common Lisp is not a single language but a specification, with many competing compiler implementations. By default, [[http://www.sbcl.org/][Steel Bank Common Lisp]] (SBCL) is assumed to be installed, but this can be configured. @@ -27,45 +16,65 @@ style often unseen in other languages. Compiled Common Lisp programs are trusted to run unmodified for a long time. ** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -This module has no dedicated maintainers. +** Module flags +/This module has no flags./ -** Module Flags +** Packages +- [[doom-package:][sly]] +- [[doom-package:][sly-macrostep]] +- [[doom-package:][sly-repl-ansi-color]] -This module provides no flags. +** Hacks +/No hacks documented for this module./ -** Plugins +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -+ [[https://github.com/joaotavora/sly][sly]] -+ [[https://github.com/joaotavora/sly-macrostep][sly-macrostep]] -+ [[https://github.com/PuercoPop/sly-repl-ansi-color][sly-repl-ansi-color]] +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites +This module requires [[http://www.sbcl.org/][SBCL]]. -This module requires the [[http://www.sbcl.org/][SBCL]] compiler to be installed. +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features - -This module does not integrate with the =lsp= module. Sly (and SLIME before it) is +This module does not integrate with [[doom-module:][:tools lsp]]. Sly (and SLIME before it) is considered the defacto development environment for Common Lisp and provides much of what is normally expected of an LSP, plus tight integration with the REPL and Emacs. ** Sly - Using this module is mostly a matter of using Sly. Please consider reading through [[http://joaotavora.github.io/sly/#A-SLY-tour-for-SLIME-users][the Sly Tour]]. -A Sly session will be started when you open a =.lisp= file. Use =SPC m '= to switch -to the REPL minibuffer. +A Sly session will be started when you open a =.lisp= file. Use [[kbd:][ ']] +to switch to the REPL minibuffer. ** org-mode - This module also enables the evaluation of =lisp= source blocks in Org Mode. -However, you will need a running Sly session for this to work. =M-x sly= starts +However, you will need a running Sly session for this to work. ~M-x sly~ starts such a session if you didn't have one open already. -* Configuration +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote If you don't want Sly to use SBCL, you can configure the variable ~inferior-lisp-program~ to some other binary on your PATH. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/coq/README.org b/modules/lang/coq/README.org index bb18d19de..66ee1e939 100644 --- a/modules/lang/coq/README.org +++ b/modules/lang/coq/README.org @@ -1,6 +1,54 @@ -#+TITLE: :lang coq +# -*- mode: doom-docs-org -*- +#+title: :lang coq +#+subtitle: Proofs as programs +#+created: August 14, 2018 +#+since: 21.12.0 (#804) +* Description :unfold: This module adds [[https://coq.inria.fr][coq]] support, powered by [[https://proofgeneral.github.io][Proof General]]. -+ Code completion ([[https://github.com/cpitclaudel/company-coq][company-coq]]) -+ [[https://github.com/hlissner/doom-snippets/tree/master/coq-mode][Snippets]] +- Code completion ([[https://github.com/cpitclaudel/company-coq][company-coq]]) +- [[https://github.com/hlissner/doom-snippets/tree/master/coq-mode][Snippets]] + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][proof-general]] +- [[doom-package:][company-coq]] + +** Hacks ++ Replaces coq-mode abbrevs with yasnippet snippets from doom's snippet library + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation ++ [[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] ++ To use the completion features of company-coq you need to enable ~(:completion company)~ ++ Make sure you have Coq installed and that the ~coqtop~ command is available. This comes with a standard installation of Coq. + You can use your linux distribution's Coq package or one of the methods given on the [[https://coq.inria.fr/download][Coq website]]. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Configuration +This module provides no additional configuration over that of the [[Packages]] it loads + +* Troubleshooting +See [[https://github.com/hlissner/doom-emacs/issues?q=is%3Aissue+is%3Aopen+label%3A%22%3Alang+coq"][related github issues]] +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/crystal/README.org b/modules/lang/crystal/README.org index 7af51c35f..729caca72 100644 --- a/modules/lang/crystal/README.org +++ b/modules/lang/crystal/README.org @@ -1,62 +1,66 @@ -#+TITLE: lang/crystal -#+DATE: January 16, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang crystal +#+subtitle: Ruby at the speed of C +#+created: January 16, 2017 +#+since: 1.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#crystal][Crystal]] - - [[#macos][MacOS]] - - [[#arch][Arch]] - - [[#icr-repl][ICR (REPL)]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This modules adds [[https://crystal-lang.org/][crystal]] support. -+ Syntax-checking (~flycheck~) -+ REPL (~inf-crystal~) +- Syntax-checking (~flycheck~) +- REPL (~inf-crystal~) ** Maintainers This module has no dedicated maintainers. -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/crystal-lang-tools/emacs-crystal-mode/][crystal-mode]] -+ [[https://github.com/brantou/inf-crystal.el/][inf-crystal]] -+ if ~:checkers syntax~ is enabled - - [[https://github.com/crystal-lang-tools/emacs-crystal-mode/][flycheck-crystal]] - - [[https://github.com/crystal-ameba/ameba.el/][flycheck-ameba]] +** Packages +- [[doom-package:][crystal-mode]] +- [[doom-package:][inf-crystal]] +- if [[doom-module:][:checkers syntax]] + - [[doom-package:][flycheck-ameba]] + - [[doom-package:][flycheck-crystal]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- [[https://crystal-lang.org/install/][The crystal compiler]] +- [[https://github.com/crystal-community/icr][ICR]], for the REPL -* Prerequisites ** Crystal -you need to install [[https://crystal-lang.org/install/][the crystal compiler]]. - -*** MacOS -#+begin_src shell -brew install crystal -#+end_src - -*** Arch -#+begin_src shell -sudo pacman -S crystal shards -#+end_src +- MacOS: ~$ brew install crystal~ +- Arch Linux: ~$ pacman -S crystal shards~ ** ICR (REPL) -you need to install [[https://github.com/crystal-community/icr][ICR]]. +[[https://github.com/crystal-community/icr#installation][Installation instructions]]. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. * TODO Configuration -# How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/csharp/README.org b/modules/lang/csharp/README.org index d3a0692f0..3cab0adfd 100644 --- a/modules/lang/csharp/README.org +++ b/modules/lang/csharp/README.org @@ -1,43 +1,78 @@ -#+TITLE: :lang csharp +# -*- mode: doom-docs-org -*- +#+title: :lang csharp +#+subtitle: Unity, .NET, and Mono shenanigans +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#macos][MacOS]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] - -* Description -This module adds C# support to Emacs. Powered by omnisharp (directly or through +* Description :unfold: +This module adds C# support to Emacs, powered by Omnisharp (directly or through LSP). -** Module Flags -+ =+lsp= Enables omnisharp through LSP support (requires omnisharp). -+ =+unity= Enables special support for the [[https://unity.com/][Unity game engine]] (particularly, - support for HLSL shaders). -+ =+dotnet= Enables Dotnet transient interface with Sharper +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/josteink/csharp-mode][csharp-mode]] -+ [[https://github.com/omajid/csproj-mode][csproj-mode]] -+ [[https://github.com/OmniSharp/omnisharp-emacs][omnisharp]]* (not =+lsp=) -+ [[https://github.com/midnightSuyama/shader-mode][shader-mode]]* (=+unity=) -+ [[https://github.com/sebasmonia/sharper][sharper]] (=+dotnet=) +** Module flags +- +dotnet :: + Enable Dotnet transient interface with Sharper +- +lsp :: + Enable LSP support for ~csharp-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports =omnisharp-roslyn=). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. +- +unity :: + Enable special support for the [[https://unity.com/][Unity game engine]] (particularly, support for + HLSL shaders). + +** Packages +- [[doom-package:][csharp-mode]] +- [[doom-package:][csproj-mode]] +- [[doom-package:][shader-mode]] if [[doom-module:][+unity]] +- [[doom-package:][sharper]] if [[doom-module:][+dotnet]] +- [[doom-package:][sln-mode]] -* Prerequisites -This module needs: +** Hacks +/No hacks documented for this module./ -+ omnisharp (with the ~+lsp~ flag, this must be installed externally. Without - it, use ~M-x omnisharp-install-server~) -+ .NET SDKs (on Windows) -+ Mono (on UNIX platforms) -+ .NET Core 1.X - 3.X or .NET 5 for cross platform +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- Mono (on UNIX platforms) +- .NET SDKs (on Windows) +- .NET Core 1.X - 3.X or .NET 5 for cross platform +- omnisharp-rosyln (if [[doom-module:][+lsp]]) ** TODO MacOS + ** Arch Linux -#+BEGIN_SRC sh -sudo pacman --needed --noconfirm -S mono -#+END_SRC +#+begin_src sh +pacman --needed --noconfirm -S mono +#+end_src + ** TODO NixOS + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/dart/README.org b/modules/lang/dart/README.org index af2441adc..1694ccd9e 100644 --- a/modules/lang/dart/README.org +++ b/modules/lang/dart/README.org @@ -1,47 +1,47 @@ -#+TITLE: lang/dart -#+DATE: February 16, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang dart +#+subtitle: Paint ui and not much else +#+created: February 15, 2020 +#+since: 21.12.0 (#2729) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#installing-dart-sdk][Installing Dart SDK]] - - [[#installing-flutter-sdk][Installing Flutter SDK]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#dart--flutter][Dart & Flutter]] - - [[#android][Android]] - - [[#flutter-mobile-development-on-desktop][Flutter mobile development on desktop]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +[[https://dart.dev/][Dart]] is a client-optimized language by Google for fast apps on any platform. It +is fast and optimized for UI, famous for the [[https://flutter.io/][Flutter]] framework, also made by +Google. Both Flutter and Dart are free and open-source. -* Description -[[https://dart.dev/][Dart]] is a client-optimized language by Google for fast apps on any platform. -It is fast and optimized for UI, famous for the [[https://flutter.io/][Flutter]] framework, also -made by Google. Both Flutter and Dart are free and open-source. - -This module wraps ~dart-mode~, with [[https://microsoft.github.io/language-server-protocol/][LSP]] features like code completion for =.dart= files, -syntax highlighting, debugging, closing labels, etc. +This module wraps ~dart-mode~, with [[https://microsoft.github.io/language-server-protocol/][LSP]] features like code completion for +=.dart= files, syntax highlighting, debugging, closing labels, etc. ** Maintainers -+ [[https://github.com/ericdallo][@ericdallo]] +- [[doom-user:][@ericdallo]] -** Module Flags -+ =+lsp= Enable LSP server integration. -+ =+flutter= Adds ~flutter~ integration and some sane defaults for Flutter - development along with ~hover~ for desktop development. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/bradyt/dart-mode][dart-mode]] -+ [[https://github.com/amake/flutter.el][flutter.el]] -+ [[https://github.com/ericdallo/hover.el][hover.el]] +** Module flags +- +flutter :: + Enable ~flutter~ integration and some sane defaults for Flutter development + along with ~hover~ for desktop development. +- +lsp :: + Enable LSP support for ~dart-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports flutter). -* Prerequisites -Make sure that the Dart SDK is on your ~PATH~, and if using Flutter, make sure -the Flutter binary is on your ~PATH~ as well. +** Packages +- [[doom-package:][dart-mode]] +- [[doom-package:][flutter.el]] +- [[doom-package:][hover.el]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +Make sure that the Dart SDK is on your =$PATH=, and if using Flutter, make sure +the Flutter binary is on your =$PATH= as well. ** Installing Dart SDK Before starting note that Flutter SDK will have a version of Dart. Therefore, @@ -52,23 +52,23 @@ The stable version of the SDK is in most major distributions repositories. If you find it necessary to install any other version or build from source, please refer to the official website at: https://dart.dev/get-dart -+ *On Debian (also Ubuntu and its derivations):* - #+BEGIN_SRC shell - sudo apt-get install dart - #+END_SRC -+ *On Arch Linux (and derivations like Manjaro):* - #+BEGIN_SRC shell - sudo pacman -S dart - #+END_SRC -+ *On macOS*: - #+BEGIN_SRC shell +- *On Debian (also Ubuntu and its derivations):* + #+begin_src sh + apt-get install dart + #+end_src +- *On Arch Linux (and derivations like Manjaro):* + #+begin_src sh + pacman -S dart + #+end_src +- *On macOS*: + #+begin_src sh brew tap dart-lang/dart brew install dart - #+END_SRC -+ *On NixOS*: - #+BEGIN_SRC shell + #+end_src +- *On NixOS*: + #+begin_src sh nix-env -iA nixpkgs.dart - #+END_SRC + #+end_src ** Installing Flutter SDK Due to complications with permissions, it is suggested not to use AUR or any @@ -77,22 +77,30 @@ automatic installation tools for Flutter SDK. On any system just run the following commands to install Flutter, once you have met dependencies named on [[https://flutter.dev/docs/get-started/install/][the site]]: -#+BEGIN_SRC shell +#+begin_src sh git clone https://github.com/flutter/flutter --branch stable # to download Flutter export PATH="$PATH:$(pwd)/flutter/bin" # to add it to PATH flutter doctor # for Dependency check and further instructions -#+END_SRC +#+end_src -* Features -+ Syntax highlighting and formatting for ~.dart~ files provided by LSP -+ Auto import -+ Widget guide lines for Flutter -+ Closing labels for constructors -+ Run tests interactively -+ Outline support via ~lsp-treemacs~ -+ Emacs functions for running and debugging Flutter projects +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- Syntax highlighting and formatting for ~.dart~ files provided by LSP. +- Auto import. +- Widget guide lines for Flutter. +- Closing labels for constructors. +- Run tests interactively. +- Outline support via [[doom-package:][lsp-treemacs]]. +- Emacs functions for running and debugging Flutter projects. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Dart & Flutter On Linux, the installers for Dart and Flutter use the ~/opt~ directory, and this module assumes that. However, you may set ~lsp-dart-sdk-dir~ to your Dart @@ -101,18 +109,31 @@ LSP can find the language server included with the Dart SDK. Alternatively, these variables shouldn't be necessary if you just include Dart and Flutter on your ~PATH~ variable. + ** Android You will also need to setup your system for Android development if you intend to use Flutter to develop mobile applications. Refer to your distributions package manager for details. In most distributions the ~/opt/android-sdk~ directory is used, and you might have to change some permissions in this directory since it's owned by root. The [[https://wiki.archlinux.org/index.php/Android][Arch Linux wiki has a great guide on this here.]] + ** Flutter mobile development on desktop [[https://github.com/go-flutter-desktop/go-flutter][Hover]] is an application that can run Flutter mobile apps on your desktop, this -makes the mobile development a lot easier without the need to setup an Android emulator. +makes the mobile development a lot easier without the need to setup an Android +emulator. * Troubleshooting +[[doom-report:][Report an issue?]] + See the configuration section for information on the binaries for Dart and -Flutter. On new installs to the ~/opt~ directory, you will likely need to edit -the permissions of the ~/opt/dart-sdk~ and ~/opt/flutter~ directories (not to +Flutter. On new installs to the =/opt= directory, you will likely need to edit +the permissions of the =/opt/dart-sdk= and =/opt/flutter= directories (not to mention the Android SDK, as discussed above). + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/data/README.org b/modules/lang/data/README.org new file mode 100644 index 000000000..9b6cf5e88 --- /dev/null +++ b/modules/lang/data/README.org @@ -0,0 +1,50 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang data +#+subtitle: A dumping ground for data formats +#+created: February 20, 2017 +#+since: 2.0.0 + +* Description :unfold: +This module adds Emacs support for CSV and XML files. + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][csv-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/dhall/README.org b/modules/lang/dhall/README.org new file mode 100644 index 000000000..ae83e039c --- /dev/null +++ b/modules/lang/dhall/README.org @@ -0,0 +1,54 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang dhall +#+subtitle: Config as code +#+created: August 03, 2021 +#+since: 21.12.0 + +* Description :unfold: +This module adds [[https://dhall-lang.org/][Dhall]] language support to Emacs. + +Dhall is a programmable configuration language that you can think of as: JSON + +functions + types + imports. + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][dhall-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires the =dhall-json= package, which provides both the +=dhall-to-json=, =dhall-to-yaml=, and =dhall-format= executables. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/elixir/README.org b/modules/lang/elixir/README.org index 44aac20eb..0b7df603c 100644 --- a/modules/lang/elixir/README.org +++ b/modules/lang/elixir/README.org @@ -1,79 +1,106 @@ -#+TITLE: lang/elixir -#+DATE: June 24, 2019 -#+SINCE: v2.0.9 +# -*- mode: doom-docs-org -*- +#+title: :lang elixir +#+subtitle: Erlang done right +#+created: May 24, 2017 +#+since: 2.0.3 (#83) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#install-elixir][Install Elixir]] - - [[#with-asdf][With ~asdf~]] - - [[#arch-linux][Arch Linux]] - - [[#gentoo-linux][Gentoo Linux]] - - [[#opensuse][openSUSE]] -- [[#features][Features]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] +* Description :unfold: +This module provides support for [[https://elixir-lang.org/][Elixir programming language]] via [[doom-package:][alchemist]] or +[[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]]. -* Description -This module provides support for [[https://elixir-lang.org/][Elixir programming language]] via [[https://github.com/tonini/alchemist.el][alchemist.el]] -or [[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]]. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] ** Module flags -+ ~+lsp~ Enable LSP support. Requires [[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]]. +- +lsp :: + Enable LSP support for ~elixir-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/elixir-lsp/elixir-ls/][elixir-ls]]). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -** Plugins -+ [[https://github.com/elixir-editors/emacs-elixir][elixir-mode]] -+ [[https://github.com/tonini/alchemist.el][alchemist.el]] -+ [[https://github.com/aaronjensen/flycheck-credo][flycheck-credo]] -+ [[https://github.com/ananthakumaran/exunit.el][exunit]] +** Packages +- [[doom-package:][alchemist]] +- [[doom-package:][elixir-mode]] +- [[doom-package:][exunit]] +- [[doom-package:][flycheck-credo]] if [[doom-module:][:checkers syntax]] -* Prerequisites -You should have Elixir installed, for example, via your distribution's package -manager or a version management tool such as [[https://github.com/asdf-vm/asdf-elixir][asdf]]. +** Hacks +/No hacks documented for this module./ -If you want to add support for LSP ([[modules/tools/lsp][:tools lsp]]), be sure to install [[https://github.com/JakeBecker/elixir-ls/][elixir-ls]] -and enable ~:tools lsp~ in your ~init.el~. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires Elixir. Install it via your distribution's package manager +or a version management tool such as [[https://github.com/asdf-vm/asdf-elixir][asdf]]. + +To add LSP support, install [[https://github.com/JakeBecker/elixir-ls/][elixir-ls]] and enable [[doom-module:][:tools lsp]]. + +To support linting with [[https://github.com/rrrene/credo][credo]], add ~:checkers syntax~ to ~$DOOMDIR/init.el~. -To support linting with [[https://github.com/rrrene/credo][credo]], add ~:checkers syntax~ to your ~init.el~ ** Install Elixir +(See [[https://elixir-lang.org/install.html]] for other operating systems) + *** With ~asdf~ -#+BEGIN_SRC sh +#+begin_src sh asdf plugin-add elixir asdf install elixir 1.9.1 -#+END_SRC +#+end_src + *** Arch Linux -#+BEGIN_SRC sh :dir /sudo:: -sudo pacman -S elixir -#+END_SRC +#+begin_src sh +pacman -S elixir +#+end_src + *** Gentoo Linux -#+BEGIN_SRC sh :dir /sudo:: -sudo emerge -v dev-lang/elixir -#+END_SRC +#+begin_src sh +emerge -v dev-lang/elixir +#+end_src *** openSUSE -#+BEGIN_SRC sh :dir /sudo:: -sudo zypper install elixir -#+END_SRC -See [[https://elixir-lang.org/install.html]] for other operating systems -* Features -- Code completion (~:completion company~) -- Documentation lookup (~:tools lookup~) +#+begin_src sh +zypper install elixir +#+end_src + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- Code completion ([[doom-module:][:completion company]]) +- Documentation lookup ([[doom-module:][:tools lookup]]) - Mix integration - Phoenix support -- ~iex~ integration (~:tools eval~) -- Syntax checking (~:checkers syntax~, using [[https://github.com/aaronjensen/flycheck-credo][flycheck-credo]]~) -* Appendix -** Commands -*** exunit-mode -The exunit-mode prefix is =SPC m t=. Here is some examples: -| | | | -| command | key / ex command | description | -|------------------------------------------+------------------+--------------------------------------------------------| -| ~exunit-verify-all~ | =SPC m t a= | Runs exunit on all files | -| ~exunit-rerun~ | =SPC m t r= | Re-runs last exunit command | -| ~exunit-verify~ | =SPC m t v= | Runs exunit on current file | -| ~exunit-verify-single~ | =SPC m t s= | Runs exunit for the item on cursor | -| ~exunit-toggle-file-and-test~ | =SPC m t t= | Switch between implementation and test | -| ~exunit-toggle-file-and-test-other-window~ | =SPC m t T= | Switch between implementation and test in other window | +- ~iex~ integration ([[doom-module:][:tools eval]]) +- Syntax checking ([[doom-module:][:checkers syntax]], using [[doom-package:][flycheck-credo]]) + +** exunit-mode +The exunit-mode prefix is [[kbd:][ t]]. Here is some examples: +| command | key / ex command | description | +|--------------------------------------------+-------------------+--------------------------------------------------------| +| ~exunit-verify-all~ | [[kbd:][ t a]] | Runs exunit on all files | +| ~exunit-rerun~ | [[kbd:][ t r]] | Re-runs last exunit command | +| ~exunit-verify~ | [[kbd:][ t v]] | Runs exunit on current file | +| ~exunit-verify-single~ | [[kbd:][ t s]] | Runs exunit for the item on cursor | +| ~exunit-toggle-file-and-test~ | [[kbd:][ t t]] | Switch between implementation and test | +| ~exunit-toggle-file-and-test-other-window~ | [[kbd:][ t T]] | Switch between implementation and test in other window | + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/elm/README.org b/modules/lang/elm/README.org new file mode 100644 index 000000000..372f92a6c --- /dev/null +++ b/modules/lang/elm/README.org @@ -0,0 +1,61 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang elm +#+subtitle: Care for a cup of TEA? +#+created: May 21, 2017 +#+since: 2.0.3 (#74) + +* Description :unfold: +This module adds [[https://elm-lang.org/][Elm]] support to Doom Emacs. + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~elm-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/elm-tooling/elm-language-server][elm-language-server]]). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. + +** Packages +- [[doom-package:][elm-mode]] +- [[doom-package:][flycheck-elm]] if [[doom-module:][:checkers syntax]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote + πŸ”¨ /This module's prerequisites are not all documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +- If [[doom-module:][+lsp]] is enabled, [[https://github.com/elm-tooling/elm-language-server][elm-language-server]] is required to be installed and in + your =$PATH=. + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/emacs-lisp/README.org b/modules/lang/emacs-lisp/README.org index 1a127563f..8f54c4b6f 100644 --- a/modules/lang/emacs-lisp/README.org +++ b/modules/lang/emacs-lisp/README.org @@ -1,60 +1,74 @@ -#+TITLE: lang/emacs-lisp -#+DATE: January 16, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang emacs-lisp +#+subtitle: A parsel-tongue for the oldest serpent +#+created: January 16, 2017 +#+since: 1.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module extends support for Emacs Lisp in Doom Emacs. -+ Macro expansion -+ Go-to-definitions or references functionality +- Macro expansion +- Go-to-definitions or references functionality +- Syntax highlighting for defined and quoted symbols +- Replaces the built-in help with the more powerful [[doom-package:][helpful]] +- Adds function example uses to documentation ** Maintainers -+ @hlissner (author) +- [[doom-user:][@hlissner]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/jorgenschaefer/emacs-buttercup][buttercup]] -+ [[https://github.com/Wilfred/elisp-def][elisp-def]] -+ [[https://github.com/xuchunyang/elisp-demos][elisp-demos]] -+ [[https://github.com/flycheck/flycheck-cask][flycheck-cask]] (=:checkers syntax=) -+ [[https://github.com/Fanael/highlight-quoted][highlight-quoted]] -+ [[https://github.com/joddie/macrostep][macrostep]] -+ [[https://github.com/tonini/overseer.el][overseer]] +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][buttercup]] +- [[doom-package:][elisp-def]] +- [[doom-package:][elisp-demos]] +- [[doom-package:][flycheck-cask]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][flycheck-package]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][highlight-quoted]] +- [[doom-package:][macrostep]] +- [[doom-package:][overseer]] ** Hacks -+ Symbols that are defined in the current session are highlighted with +- Symbols that are defined in the current session are highlighted with ~font-lock-variable-face~. -+ Eldoc will display the values of variables next to its documentation. -+ ~elisp-demos~ was modified to display API demos for Doom's standard library +- Eldoc will display the values of variables next to its documentation. +- ~elisp-demos~ was modified to display API demos for Doom's standard library (in [[file:../../../docs/api.org][docs/api.org]]). -+ This module extends imenu support for Doom's API (e.g. ~package!~, +- This module extends imenu support for Doom's API (e.g. ~package!~, ~use-package~, ~after!~) -+ Flycheck has been configured to tone down the false positives when you are +- Flycheck has been configured to tone down the false positives when you are editing your Emacs or Doom config. -* Prerequisites +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + This module's sole dependency is Emacs. It's very obscure, you wouldn't know about it. -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration -# How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/emacs-lisp/autoload.el b/modules/lang/emacs-lisp/autoload.el index b0b60ef8d..99360ee57 100644 --- a/modules/lang/emacs-lisp/autoload.el +++ b/modules/lang/emacs-lisp/autoload.el @@ -95,7 +95,7 @@ if it's callable, `apropos' otherwise." (with-demoted-errors "%s" (re-search-forward (if (caddr module) - "\\* Module Flags$" + "\\* Module flags$" "\\* Description$")) (when (caddr module) (re-search-forward (format "=\\%s=" (caddr module)) diff --git a/modules/lang/emacs-lisp/demos.org b/modules/lang/emacs-lisp/demos.org index 14538d435..90ffce168 100644 --- a/modules/lang/emacs-lisp/demos.org +++ b/modules/lang/emacs-lisp/demos.org @@ -1,5 +1,5 @@ -#+TITLE: API Demos -#+PROPERTY: header-args:emacs-lisp :results verbatim +#+title: API Demos +#+property: header-args:elisp :results pp This file contains demos of Doom's public API; its core library, macros, and autodefs. It is used by the =elisp-demos= package to display examples of their diff --git a/modules/lang/erlang/README.org b/modules/lang/erlang/README.org index b5b540c97..60d1fa337 100644 --- a/modules/lang/erlang/README.org +++ b/modules/lang/erlang/README.org @@ -1,39 +1,61 @@ -#+TITLE: lang/erlang -#+DATE: January 14, 2020 -#+SINCE: {replace with next tagged release version} -#+STARTUP: inlineimages nofold - -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - -* Description +# -*- mode: doom-docs-org -*- +#+title: :lang erlang +#+subtitle: an elegant language for a more civilized age +#+created: April 07, 2018 +#+since: 21.12.0 (#497) +* Description :unfold: This module provides support [[https://www.erlang.org/][Erlang programming language]]. Support for the [[https://github.com/erlang/sourcer][sourcer]] language server is optional. +Includes: +- Code completion ([[doom-module:][+lsp]], [[doom-module:][:completion company]], & [[doom-module:][:completion ivy]]) +- Syntax checking ([[doom-module:][:checkers syntax]]) + ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ ~+lsp~ Enable LSP Support. Requires [[https://github.com/erlang/sourcer][sourcer]]. +** Module flags +- +lsp :: + Enable LSP support for ~erlang-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/erlang/sourcer][sourcer]]). +** Packages +- [[doom-package:][flycheck-rebar3]] +- [[doom-package:][ivy-erlang-complete]] -** Plugins -+ Erlang Mode (bundled with Erlang installations) -+ [[https://github.com/joedevivo/flycheck-rebar3][flycheck-rebar3]] -+ [[https://github.com/s-kostyaev/ivy-erlang-complete][ivy-erlang-complete]] +** Hacks +/No hacks documented for this module./ -* Prerequisites -You should have Erlang installed. Check your distribution's package manager or a -version management tool such as [[https://github.com/kerl/kerl][kerl]]. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -If you want LSP support, install [[https://github.com/erlang/sourcer][sourcer]]. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Features -- Code completion (~+lsp~, ~:completion company~, and ~:completion ivy~) -- Syntax checking (~:checkers syntax~) +This module requires Erlang be installed (which includes ~erlang-mode~). Check +your distribution's package manager or a version management tool such as [[https://github.com/kerl/kerl][kerl]]. + +For LSP support, install [[https://github.com/erlang/sourcer][sourcer]]. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/ess/README.org b/modules/lang/ess/README.org index a50f434d7..febca9006 100644 --- a/modules/lang/ess/README.org +++ b/modules/lang/ess/README.org @@ -1,34 +1,66 @@ -#+TITLE: :lang ess +# -*- mode: doom-docs-org -*- +#+title: :lang ess +#+subtitle: 73.6% of all statistics are made up +#+created: February 05, 2018 +#+since: 21.12.0 (#410) +* Description :unfold: This module adds support for various statistics languages, including R, S-Plus, SAS, Julia and Stata. -* Table of Contents :TOC: -- [[#prequisites][Prequisites]] -- [[#appendix][Appendix]] - - [[#keybindings][Keybindings]] +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +stan :: + Enable support for ~stan-mode~, including code completion and syntax checking. + +** Packages +- [[doom-package:][ess]] +- [[doom-package:][ess-R-data-view]] +- [[doom-package:][polymode]] +- [[doom-package:][poly-R]] +- if [[doom-module:][+stan]] + - [[doom-package:][company-stan]] if [[doom-module:][:completion company]] + - [[doom-package:][eldoc-stan]] + - [[doom-package:][flycheck-stan]] if [[doom-module:][:checkers syntax]] + - [[doom-package:][stan-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prequisites This module has several optional dependencies: -+ [[https://github.com/jimhester/lintr][lintr]]: Enables R linting. -+ [[https://github.com/REditorSupport/languageserver][languageserver]]: Enables LSP support in an R buffer (with =+lsp= flag). - -* Appendix -** Keybindings -*** :map ess-doc-map +- [[https://github.com/jimhester/lintr][lintr]]: for R linting. +- [[https://github.com/REditorSupport/languageserver][languageserver]]: for LSP support in an R buffer (with [[doom-module:][+lsp]] flag). + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +** :map ess-doc-map | key | command | |-----+----------------------------| | "h" | ess-display-help-on-object | | "p" | ess-R-dv-pprint | | "t" | ess-R-dv-ctable | -*** :map ess-mode-map + +** :map ess-mode-map | key | command | |--------------+-----------------------| | "" | ess-eval-line | | "" | comint-next-input | | "" | comint-previous-input | -**** :localleader + +** :localleader | state | key | command | |-------+-------------+---------------------------------------------------| | :nv | "," | ess-eval-region-or-function-or-paragraph-and-step | @@ -55,3 +87,19 @@ This module has several optional dependencies: | :n | "cm" | ess-noweb-mark-chunk | | :n | "cp" | ess-noweb-previous-chunk | | :n | "cn" | ess-noweb-next-chunk | + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/factor/README.org b/modules/lang/factor/README.org index e697945dc..49e7836c0 100644 --- a/modules/lang/factor/README.org +++ b/modules/lang/factor/README.org @@ -1,43 +1,58 @@ -#+TITLE: lang/factor -#+DATE: December 3, 2019 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang factor +#+subtitle: ... +#+created: December 03, 2019 +#+since: 21.12.0 (#2129) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds support to the [[https://github.com/factor/factor][factor]] programming language and its associated -_fuel_ emacs plugin. +[[doom-package:][fuel]] emacs plugin. -+ If possible, include a brief list of feature highlights here -+ Like code completion, syntax checking or available snippets -+ Include links to packages & external things where possible +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -{A list of linked plugins} +** Packages +/This module doesn't install any packages./ ** Hacks -{A list of internal modifications to included packages} +/No hacks documented for this module./ -* Prerequisites -You must install [[https://github.com/factor/factor][factor]] to use the advanced functionality of this module. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires [[https://github.com/factor/factor][factor]] for its advanced functionality. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration This module requires the installation of factor to be available at -=fuel-factor-root-dir=. Here's an example of how to set it: -#+BEGIN_SRC emacs-lisp +~fuel-factor-root-dir~. E.g. +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq fuel-factor-root-dir "/Applications/factor") -#+END_SRC +#+end_src * Troubleshooting -Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/faust/README.org b/modules/lang/faust/README.org index 227c7dc1a..721045cee 100644 --- a/modules/lang/faust/README.org +++ b/modules/lang/faust/README.org @@ -1,46 +1,70 @@ -#+TITLE: lang/faust -#+DATE: July 23, 2019 -#+SINCE: v2.1.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang faust +#+subtitle: DSP, but you can keep your soul +#+created: October 14, 2019 +#+since: 21.12.0 (#1898) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#plugins][Plugins]] -- [[#features][Features]] +* Description :unfold: +Add support to [[https://faust.grame.fr/][Faust language]] inside emacs. -* Description -Add support to Faust language inside emacs. +- Faust code syntax highlighting and indentation +- Project-based (inter-linked Faust files) +- Build/compile with output window +- Graphic diagrams generation and visualization in the (default) browser +- Browse generated C++ code inside Emacs +- Inter-linked files/buffers : + - From "component" to Faust file + - From "include" to Faust library file +- From error to file:line number +- From function name to online documentation +- Fully configurable (build type/target/architecture/toolkit, keyboard + shortcuts, etc.) +- Automatic keyword completion (if Auto-Complete is installed) +- Automatic objets (functions, operators, etc.) template insertion with default + sensible values (if [[doom-module:][:editor snippets]] is enabled) +- Modeline indicator of the state of the code -+ Faust code syntax hightlighting and indentation -+ Project-based (inter-linked Faust files) -+ Build/compile with output window -+ Graphic diagrams generation and vizualisation in the (default) browser -+ Browse generated C++ code inside Emacs -+ Inter-linked files/buffers : - + From "component" to Faust file - + From "include" to Faust library file -+ From error to file:line number -+ From function name to online documentation -+ Fully configurable (build type/target/architecture/toolkit, keyboard shortcuts, etc.) -+ Automatic keyword completion (if Auto-Complete is installed) -+ Automatic objets (functions, operators, etc.) template insertion with default sensible values (if Yasnippet is installed) -+ Modeline indicator of the state of the code +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://bitbucket.org/yphil/faustine][faustine]] +** Packages +- [[doom-package:][faustine]] -* Features -Keybindings +** Hacks +- Both ~faust-mode~ and ~faustine-mode~ are hardcoded to use [[doom-package:][auto-complete]], + which Doom does not use. Its obnoxious 'You really should install and use + auto-complete' warnings have been silenced. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote | Binding | Description | |-------------------+----------------------| -| ~ b~ | ~build~ | -| ~ c~ | ~syntax check~ | -| ~ d~ | ~diagram~ | -| ~ h~ | ~online dock~ | -| ~ RET~ | ~mdoc~ | -| ~ o~ | ~toggle output buffer~ | -| ~ s~ | ~source code~ | -| ~ r~ | ~run~ | -| ~ S-b~ | ~build all~ | -| ~ S-d~ | ~diagram all~ | +| [[kbd:][ b]] | build | +| [[kbd:][ c]] | syntax check | +| [[kbd:][ d]] | diagram | +| [[kbd:][ h]] | online dock | +| [[kbd:][ RET]] | mdoc | +| [[kbd:][ o]] | toggle output buffer | +| [[kbd:][ s]] | source code | +| [[kbd:][ r]] | run | +| [[kbd:][ S-b]] | build all | +| [[kbd:][ S-d]] | diagram all | + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/fsharp/README.org b/modules/lang/fsharp/README.org index bb37fdf73..81b3193c5 100644 --- a/modules/lang/fsharp/README.org +++ b/modules/lang/fsharp/README.org @@ -1,58 +1,71 @@ -#+TITLE: lang/fsharp -#+DATE: May 22, 2019 -#+SINCE: {replace with next tagged release version} -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang fsharp +#+subtitle: ML stands for Microsoft's Language +#+created: May 23, 2019 +#+since: 21.12.0 (#1327) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] - - [[#mono][Mono]] - - [[#osx][OSX]] - - [[#arch-linux][Arch Linux]] - - [[#lsp][LSP]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module adds [[https://fsharp.org/][F#]] support to Doom Emacs. -* Description -# A summary of what this module does. +*Includes:* +- Code completion +- eldoc support +- Syntax checking -# + If possible, include a brief list of feature highlights here -# + Like code completion, syntax checking or available snippets -# + Include links to packages & external things where possible -This module adds [[https://fsharp.org/][F#]] support. -+ Code completion -+ eldoc support -+ Syntax checking +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~fsharp-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-fsharp.el][lsp-fsharp]].). + +** Packages +- [[doom-package:][fsharp-mode]] +- [[doom-package:][lsp-fsharp]] if [[doom-package:][+lsp]] -** Module Flags -+ =+lsp= Enables lsp-fsharp (this requires ~:tools lsp~ to be enabled). -** Plugins -+ [[https://github.com/fsharp/emacs-fsharp-mode][fsharp-mode]] -+ =+lsp= - + [[https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-fsharp.el][lsp-fsharp]] ** Hacks -None so far. +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +To get code completion/syntax checking when not using lsp, you will need to +install [[https://www.mono-project.com/][mono]]. -* Prerequisites ** Mono -To get code completion/syntax checking when not using lsp, you will need to install [[https://www.mono-project.com/][mono]]. *** OSX -Do *NOT* install mono via brew. See this [[https://github.com/fsharp/FsAutoComplete/issues/331][issue]]. +*Do NOT install mono via brew.* See this [[https://github.com/fsharp/FsAutoComplete/issues/331][issue]]. + *** Arch Linux -#+BEGIN_SRC sh -sudo pacman -S mono -#+END_SRC +#+begin_src sh +pacman -S mono +#+end_src + ** LSP The language server is automatically installed by [[https://github.com/emacs-lsp/lsp-mode/blob/master/clients/lsp-fsharp.el][lsp-fsharp]]. -* Features -An in-depth list of features, how to use them, and their dependencies. -* Configuration -How to configure this module, including common problems and how to address them. +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/fstar/README.org b/modules/lang/fstar/README.org index 30b025eaa..fe6ff254e 100644 --- a/modules/lang/fstar/README.org +++ b/modules/lang/fstar/README.org @@ -1,56 +1,74 @@ -#+TITLE: lang/fstar -#+DATE: February 2, 2020 -#+SINCE: 2.0.10 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang fstar +#+subtitle: (Dependent) types and (monadic) effects and Z3 +#+created: February 02, 2020 +#+since: 21.12.0 (#2473) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#f][F*]] - - [[#macos][macOS]] - - [[#arch-linux][Arch Linux]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds [[https://fstar-lang.org/][F*]] support, powered by [[https://github.com/FStarLang/fstar-mode.el][fstar-mode.el]]. -+ Syntax highlighting -+ Interactively process F* files one definition at a time -+ Query the running F* process to look up definitions, documentation, and +- Syntax highlighting +- Interactively process F* files one definition at a time +- Query the running F* process to look up definitions, documentation, and theorems ** Maintainers -+ [[https://github.com/tchajed][@tchajed]] (Author) +- [[doom-user:][@tchajed]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/FStarLang/fstar-mode.el][fstar-mode]] +** Module flags +/This module has no flags./ -* Prerequisites -** F* -While fstar-mode supports the latest release of F*, you may have a better -experience installing a more recent version from source. See F*'s [[https://github.com/FStarLang/FStar/blob/master/INSTALL.md][INSTALL.md]]. -*** macOS -#+BEGIN_SRC sh +** Packages +- [[doom-package:][fstar-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires [[https://github.com/FStarLang/FStar/blob/master/INSTALL.md][F*]]. + +While ~fstar-mode~ supports the latest release of F*, you may have a better +experience installing a more recent version from source. + +** macOS +#+begin_src sh brew install fstar -#+END_SRC -*** Arch Linux -Install ~fstar~ from the AUR: -#+BEGIN_SRC sh +#+end_src + +** Arch Linux +~fstar~ is available in the AUR: +#+begin_src sh yaourt -S fstar -#+END_SRC +#+end_src -* Features +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* Configuration +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -If you're having trouble getting F* to start correctly, you may need to -configure a few variables in fstar-mode; see its [[https://github.com/FStarLang/fstar-mode.el][README]] for more details. +[[doom-report:][Report an issue?]] + +- If you're having trouble getting F* to start correctly, you may need to + configure a few variables in ~fstar-mode~; see its [[https://github.com/FStarLang/fstar-mode.el][README]] for more details. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/gdscript/README.org b/modules/lang/gdscript/README.org index 45cb1d3e2..8e18bc23b 100644 --- a/modules/lang/gdscript/README.org +++ b/modules/lang/gdscript/README.org @@ -1,55 +1,79 @@ -#+TITLE: lang/gdscript -#+DATE: May 27, 2020 -#+SINCE: v2.0.9 +# -*- mode: doom-docs-org -*- +#+title: :lang gdscript +#+subtitle: the language you waited for +#+created: June 01, 2020 +#+since: 21.12.0 (#3239) -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] - -* Description +* Description :unfold: This module adds support for GDScript, the scripting language of the [[http://godotengine.org/][Godot]] game engine, to Doom Emacs, powered by [[https://github.com/GDQuest/emacs-gdscript-mode][gdscript-mode]]. -** Module Flags -+ =+lsp= Enables LSP support for gdscript-mode. This requires the =:tools lsp= - module to be enabled and you need to open your project in Godot ~3.2.1~ or - above to run the language server. +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -This module provides no plugins. +** Module flags +- +lsp :: + Enable LSP support for ~gdscript-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (Godot ~3.2.1~ or newer). -* Prerequisites -To format your GDScript code, you need to install [[https://github.com/Scony/godot-gdscript-toolkit/][gdtoolkit]]: +** Packages +- [[doom-package:][gdscript-mode]] -#+BEGIN_SRC shell +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires Godot 3.2.1+ to be installed to make use of any of its +features (beyond syntax highlighting). + +To format your GDScript code, you will need [[https://github.com/Scony/godot-gdscript-toolkit/][gdtoolkit]]: +#+begin_src sh # On Windows pip install gdtoolkit # On MacOS and Linux pip3 install gdtoolkit -#+END_SRC +#+end_src -* Features +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +** LSP support The language server support for GDScript is built into by lsp-mode. As long as -you have the ~lsp~ module installed, you should be able to use the language -server. +you have [[doom-module:][+lsp]] and [[doom-module:][:tools lsp]] enabled, and Godot 3.2.1+ installed, it should work +out of the box. Godot's language server is built into the game engine, so you need to open your project in Godot ~3.2.1~ or above for the GDScript language server to be available. -/Note that the GDScript language server has known issues causing some errors -with lsp-mode. They should be addressed in future releases./ - -* Configuration -This module provides no configuration. - -* Appendix ** Commands -Press ~SPC m~ (local leader key) to explore available commands. +Press the localleader key ([[kbd:][SPC m]] for evil users, [[kbd:][C-c l]] otherwise) to explore +available commands. + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +[[doom-report:][Report an issue?]] + +- The GDScript language server has known issues causing some errors with + [[doom-package:][lsp-mode]]. They should be addressed in future releases. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/go/README.org b/modules/lang/go/README.org index e0b7fd946..63da4be82 100644 --- a/modules/lang/go/README.org +++ b/modules/lang/go/README.org @@ -1,81 +1,76 @@ -#+TITLE: lang/go -#+DATE: January 16, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang go +#+subtitle: The hipster dialect +#+created: June 15, 2015 +#+since: 0.7 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#go][Go]] - - [[#dependencies][Dependencies]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module adds [[https://golang.org][Go]] support, with optional (but recommended) LSP support via [[https://github.com/golang/tools/blob/master/gopls/README.md][gopls]]. -+ Code completion (~gocode~) -+ Documentation lookup (~godoc~) -+ Eldoc support (~go-eldoc~) -+ REPL (~gore~) -+ Syntax-checking (~flycheck~) -+ Auto-formatting on save (~gofmt~) (requires =:editor (format +onsave)=) -+ Code navigation & refactoring (~go-guru~) -+ [[../../editor/file-templates/templates/go-mode][File templates]] -+ [[https://github.com/hlissner/doom-snippets/tree/master/go-mode][Snippets]] -+ Generate testing code (~go-gen-test~) -+ Code checking (~flycheck-golangci-lint~) +- Code completion (~gocode~) +- Documentation lookup (~godoc~) +- Eldoc support (~go-eldoc~) +- REPL (~gore~) +- Syntax-checking (~flycheck~) +- Auto-formatting on save (~gofmt~) (requires [[doom-module:][:editor format +onsave]]) +- Code navigation & refactoring (~go-guru~) +- [[../../editor/file-templates/templates/go-mode][File templates]] +- [[https://github.com/hlissner/doom-snippets/tree/master/go-mode][Snippets]] +- Generate testing code (~go-gen-test~) +- Code checking (~flycheck-golangci-lint~) -** Module Flags -+ =+lsp= Enables integration for the gopls LSP server. It is highly recommended - you use this, as the non-LSP experience is deprecated (and poor). +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/dominikh/go-mode.el][go-mode]] -+ [[https://github.com/syohex/emacs-go-eldoc][go-eldoc]] -+ [[https://github.com/dominikh/go-mode.el][go-guru]] -+ [[https://github.com/manute/gorepl-mode][gorepl-mode]] -+ [[https://github.com/brantou/emacs-go-tag][go-tag]] -+ [[https://github.com/mdempsky/gocode][company-go]]* =DEPRECATED= -+ [[https://github.com/s-kostyaev/go-gen-test][go-gen-test]] -+ [[https://github.com/weijiangan/flycheck-golangci-lint][flycheck-golangci-lint]] (if =:checkers syntax= is enabled) +** Module flags +- +lsp :: + Enable LSP support for ~go-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports gopls). Highly recommended, as the non-LSP experience is deprecated + (and poor). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. + +** Packages +- [[doom-package:][company-go]] if [[doom-module:][:completion company]] (DEPRECATED) +- [[doom-package:][flycheck-golangci-lint]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][go-eldoc]] +- [[doom-package:][go-gen-test]] +- [[doom-package:][go-guru]] +- [[doom-package:][go-mode]] +- [[doom-package:][gorepl-mode]] +- [[doom-package:][go-tag]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires Go, a valid =$GOPATH=, and a number of go packages, listed +below. -* Prerequisites ** Go -To get started with Go, you need the ~go~ tool: - -*** MacOS -#+BEGIN_SRC bash -brew install go -#+END_SRC - -*** Arch Linux -#+BEGIN_SRC bash -sudo pacman -S go -#+END_SRC - -*** openSUSE -#+BEGIN_SRC sh :dir /sudo:: -sudo zypper install go -#+END_SRC +- macOS: ~$ brew install go~ +- Arch Linux: ~$ pacman -S go~ +- openSUSE: ~$ zypper install go~ ** Dependencies -This module requires a valid ~GOPATH~, and the following Go packages: +- ~gocode~ (for code completion & eldoc support) +- ~godoc~ (for documentation lookup) +- ~gorename~ (for extra refactoring commands) +- ~gore~ (for the REPL) +- ~guru~ (for code navigation & refactoring commands) +- ~goimports~ (/optional/: for auto-formatting code on save & fixing imports) +- ~gotests~ (for generate test code) +- ~gomodifytags~ (for manipulating tags) -+ ~gocode~ (for code completion & eldoc support) -+ ~godoc~ (for documentation lookup) -+ ~gorename~ (for extra refactoring commands) -+ ~gore~ (for the REPL) -+ ~guru~ (for code navigation & refactoring commands) -+ ~goimports~ (optional: for auto-formatting code on save & fixing imports) -+ ~gotests~ (for generate test code) -+ ~gomodifytags~ (for manipulating tags) - -#+BEGIN_SRC sh +#+begin_src sh export GOPATH=~/work/go go install github.com/x-motemen/gore/cmd/gore@latest @@ -86,14 +81,29 @@ go install golang.org/x/tools/cmd/gorename@latest go install golang.org/x/tools/cmd/guru@latest go install github.com/cweill/gotests/gotests@latest go install github.com/fatih/gomodifytags@latest -#+END_SRC +#+end_src -+ ~golangci-lint~ (optional: for flycheck to integrate golangci-lint results) - it is recommended to *not* use ~go get~ to install this one, check the +- ~golangci-lint~ (optional: for flycheck to integrate golangci-lint results) it + is recommended to *not* use ~$ go get~ to install this one, check the [[https://github.com/golangci/golangci-lint#binary-release][documentation]]. -* TODO Features +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/haskell/README.org b/modules/lang/haskell/README.org index 971ef7e1d..a2b83aa00 100644 --- a/modules/lang/haskell/README.org +++ b/modules/lang/haskell/README.org @@ -1,43 +1,42 @@ -#+TITLE: lang/haskell -#+DATE: January 16, 2017 -#+SINCE: v0.7 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang haskell +#+subtitle: A language that's lazier than I am +#+created: March 29, 2016 +#+since: 0.9 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - -* Description -Adds Haskell support to Doom Emacs. +* Description :unfold: +This module adds Haskell support to Doom Emacs. ** Maintainers -This module has no dedicated maintainers. +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+lsp= Enable LSP support with for [[https://github.com/haskell/haskell-language-server][haskell-language-server]] (requires the =:tools lsp= module). +** Module flags +- +lsp :: + Enable LSP support for ~haskell-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/haskell/haskell-language-server][haskell-language-server]]). -** Plugins -+ [[https://github.com/haskell/haskell-mode][haskell-mode]] -+ [[https://github.com/emacs-lsp/lsp-haskell][lsp-haskell]] (=+lsp=, =:tools lsp=) +** Packages +- [[doom-package:][haskell-mode]] +- [[doom-package:][lsp-haskell]] if [[doom-module:][+lsp]] + +** Hacks +/No hacks documented for this module./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites It is recommended to install the haskell tooling using [[https://www.haskell.org/ghcup/][ghcup]]. Only ghc is needed for basic functionality: -#+BEGIN_SRC bash +#+begin_src sh ghcup install ghc -#+END_SRC +#+end_src but =+lsp= users should also install the language server: -#+BEGIN_SRC bash +#+begin_src sh ghcup install hls -#+END_SRC +#+end_src Installing [[https://www.haskell.org/cabal/][cabal]] or [[https://docs.haskellstack.org/en/stable/README/][stack]] as well is recommended, and can be done through =ghcup=. @@ -49,25 +48,44 @@ system package manager, cabal, or stack. formatters such as [[https://github.com/lspitzner/brittany][brittany]], [[https://github.com/ennocramer/floskell][floskell]], [[https://github.com/tweag/ormolu][ormolu]], [[https://github.com/fourmolu/fourmolu][fourmolu]], and [[https://github.com/haskell/stylish-haskell][stylish-haskell]], which can be installed through system package manager, cabal, or stack. -* Features -This module intergrates the haskell packages into Doom by providing things such -as repl support, project root recognition, etc. It also provide the following +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +This module integrates the haskell packages into Doom by providing things such +as REPL support, project root recognition, etc. It also provide the following keybindings: -| Keybinding | Description | -|-------------------+-----------------------------------------------| -| = b= | Build the current cabal project | -| = c= | Visit the =.cabal= file of the current buffer | -| = h= | Toggle visibility of the form at point | -| = H= | hides all top level functions | +| Keybinding | Description | +|-----------------+-----------------------------------------------| +| [[kbd:][ b]] | Build the current cabal project | +| [[kbd:][ c]] | Visit the =.cabal= file of the current buffer | +| [[kbd:][ h]] | Toggle visibility of the form at point | +| [[kbd:][ H]] | hides all top level functions | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration After installing your preferred formatter, make sure to set =lsp-haskell-formatting-provider= to it. Make sure to configure the lsp to use your perfered formatter, e.g.: -#+BEGIN_SRC elisp +#+begin_src emacs-lisp ;; ~/.doom.d/config.el -(after! +(after! lsp-haskell (setq lsp-haskell-formatting-provider "brittany")) -#+END_SRC +#+end_src + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/hy/README.org b/modules/lang/hy/README.org new file mode 100644 index 000000000..63ab77deb --- /dev/null +++ b/modules/lang/hy/README.org @@ -0,0 +1,50 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang hy +#+subtitle: Lisp is better than ugly +#+created: June 25, 2017 +#+since: 2.0.4 (#122) + +* Description :unfold: +/(No description yet)/ + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][hy-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires [[https://docs.hylang.org/en/alpha/][Hy]]. + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/idris/README.org b/modules/lang/idris/README.org index e21ac8633..a7edac3d3 100644 --- a/modules/lang/idris/README.org +++ b/modules/lang/idris/README.org @@ -1,30 +1,55 @@ -#+TITLE: lang/idris -#+DATE: October 6, 2020 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang idris +#+subtitle: A language you can depend on +#+created: August 21, 2018 +#+since: 21.12.0 (#822) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] +* Description :unfold: +This module adds rudimentary [[https://www.idris-lang.org/][Idris]] support to Doom Emacs. -* Description -This module adds rudimentary Idris support. ** Maintainers -This module has no dedicated maintainers. +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -# A list of linked plugins -+ [[https://github.com/idris-hackers/idris-mode/][idris-mode]] +** Packages +- [[doom-package:][idris-mode]] -* Prerequisites -This module has no prerequisites. +** Hacks +/No hacks documented for this module./ -* Features -In addition to =idris-mode= goodness, adds frequently used functions under the localleader key. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote + πŸ”¨ /No installation steps have been documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +In addition to ~idris-mode~ goodness, adds frequently used functions under the +[[kbd:][]] key. + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/java/README.org b/modules/lang/java/README.org index 4449c18f6..e5f5bf12f 100644 --- a/modules/lang/java/README.org +++ b/modules/lang/java/README.org @@ -1,148 +1,171 @@ -#+TITLE: lang/java -#+DATE: January 16, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang java +#+subtitle: The poster child for carpal tunnel syndrome +#+created: January 16, 2017 +#+since: 1.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] -- [[#prerequisites][Prerequisites]] - - [[#openjdk-11][OpenJDK 11]] - - [[#ubuntu][Ubuntu]] - - [[#fedora][Fedora]] - - [[#oracle-jdk-11][Oracle JDK 11]] - - [[#ubuntu-1][Ubuntu]] - - [[#fedora-1][Fedora]] - - [[#multiple-java-versions][Multiple Java Versions]] -- [[#features][Features]] - - [[#lsp-features][=+lsp= features]] - - [[#meghanada-features][=+meghanada= features]] -- [[#configuration][Configuration]] - - [[#lsp][=+lsp=]] +* Description :unfold: +This module adds [[https://www.java.com][Java]] support to Doom Emacs, including ~android-mode~ and +~groovy-mode~. -* Description -This module adds [[https://www.java.com][java]] support to Doom Emacs, including =android-mode= and -=groovy-mode=. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+lsp= Enables integration for the eclipse.jdt.ls LSP server. -+ =+meghanada= Enables the [[https://github.com/mopemope/meghanada-emacs/tree/master][meghanada-mode]] +** Module flags +- +lsp :: + Enable LSP support for ~java-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports eclipse.jdt.ls). *Incompatible with [[doom-module:][+meghanada]].* +- +meghanada :: + Enable [[doom-package:][meghanada-mode]]. *Incompatible with [[doom-module:][+lsp]].* +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -The =+lsp= and =+meghanada= packages are mutually exclusive and do not work -together. At the time of writing the =+meghanada= is already configured whereas -=+lsp= needs to manual configuring. +** Packages +- [[doom-package:][android-mode]] +- [[doom-package:][groovy-mode]] +- [[doom-package:][meghanada]] if [[doom-module:][+meghanada]] +- if [[doom-module:][+eclim]] + - [[doom-package:][eclim]] + - [[doom-package:][company-emacs-eclim]] if [[doom-module:][:completion company]] +- if [[doom-module:][+lsp]] and not [[doom-module:][:tools lsp +eglot]] + - [[doom-package:][lsp-java]] -The =lsp= test runner requires that =:tools (debugger +lsp)= is enabled, as this -provides =dap-mode= which contains the Java test runner. +** Hacks +/No hacks documented for this module./ -* Prerequisites -This module requires the Java SDK. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- [[https://www.oracle.com/java/technologies/downloads/][Java SDK]] +- The LSP test runner requires [[doom-module:][:tools debugger +lsp]] (requires [[doom-package:][dap-mode]]) ** OpenJDK 11 *** Ubuntu -#+BEGIN_SRC sh -sudo apt-get install openjdk-11-jdk-headless -#+END_SRC +#+begin-src sh +apt-get install openjdk-11-jdk-headless +#+end_src + *** Fedora -#+BEGIN_SRC sh -sudo dnf install java-11-openjdk -#+END_SRC +#+begin_src sh +dnf install java-11-openjdk +#+end_src ** Oracle JDK 11 *** Ubuntu -#+BEGIN_SRC sh -sudo add-apt-repository ppa:linuxuprising/java -sudo apt update -sudo apt install oracle-java11-installer -sudo apt install oracle-java11-set-default -#+END_SRC +#+begin_src sh +add-apt-repository ppa:linuxuprising/java +apt update +apt install oracle-java11-installer +apt install oracle-java11-set-default +#+end_src + *** Fedora -#+BEGIN_SRC sh +#+begin_src sh curl -O https://download.java.net/java/GA/jdk11/9/GPL/openjdk-11.0.2_linux-x64_bin.tar.gz tar zxvf openjdk-11.0.2_linux-x64_bin.tar.gz sudo mv jdk-11.0.2/ /usr/local/ -#+END_SRC +#+end_src -Open =/etc/profile.d/jdk11.sh= as root and add - -#+BEGIN_SRC sh +Open =/etc/profile.d/jdk11.sh= as root and add: +#+begin_src sh export JAVA_HOME=/usr/local/jdk-11.0.2 export PATH=$PATH:$JAVA_HOME/bin -#+END_SRC +#+end_src -Save the file and source the file - -#+BEGIN_SRC sh +Save the file and source it: +#+begin_src sh source /etc/profile.d/jdk11.sh java -version -#+END_SRC +#+end_src ** Multiple Java Versions It is common to need support for multiple Java versions. You can use a generic tool like [[https://github.com/shyiko/jabba][jabba]] to install and manage multiple Java versions on any OS. -To switch between Java versions in Doom, you can use [[https://github.com/direnv/direnv][direnv]] and the [[file:~/.emacs.d/modules/tools/direnv/README.org::+TITLE: tools/direnv][direnv module]]. To set a -Java version for a particular project, create a =.envrc= pointing to the Java -installation in the root of the project: - -#+BEGIN_SRC conf-unix +To have a different version of Java per-project, it is recommended you use +[[https://github.com/direnv/direnv][direnv]] and [[doom-module:][:tools direnv]]; create a =.envrc= in the root of the project pointing +to the Java installation: +#+begin_src sh PATH_add ~/.jabba/jdk/adopt@1.11.0-3 JAVA_HOME=~/.jabba/jdk/adopt@1.11.0-3 -#+END_SRC +#+end_src -And then run =direnv allow .= in the project directory. If the =direnv= module -is enabled, then Doom will automatically source this environment before -executing the LSP server. +And then run ~$ direnv allow .~ in the project directory. The [[doom-module:][:tools direnv]] +module will automatically source this environment before activating LSP servers. -* Features -** =+lsp= features -According to [[https://github.com/emacs-lsp/lsp-java]] it adds +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -+ As you type reporting of parsing and compilation errors (via flycheck/[[https://github.com/emacs-lsp/lsp-ui][lsp-ui]]) -+ Code completion - using [[https://github.com/tigersoldier/company-lsp][company-lsp]] or builtin complete-at-point -+ Javadoc hovers - using [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]] -+ Code actions - using [[https://github.com/emacs-lsp/lsp-ui][lsp-ui]] -+ Code outline - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Imenu.html][imenu]] -+ Code navigation - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html][xref]] -+ Code lens (references/implementations) - using builtin [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html][xref]] -+ Highlights -+ Code formatting -+ Maven pom.xml project support -+ Limited Gradle support -+ Visual debugger - [[https://github.com/yyoncho/dap-mode/][dap-mode]] -+ Test runner - [[https://github.com/yyoncho/dap-mode/][dap-mode]] -+ Project explorer integration - [[https://github.com/Alexander-Miller/treemacs][treemacs]] -+ Integration with [[https://start.spring.io/][Spring Initializr]] +** [[doom-module:][+lsp]] features +According to [[https://github.com/emacs-lsp/lsp-java]], you get: +- As you type reporting of parsing and compilation errors (via [[doom-package:][flycheck]] or + [[doom-package:][lsp-ui]]) +- Code completion ([[doom-package:][company-lsp]] or complete-at-point) +- Javadoc hovers ([[doom-package:][lsp-ui]]) +- Code actions ([[doom-package:][lsp-ui]]) +- Code outline ([[doom-package:][imenu]]) +- Code navigation ([[doom-package:][xref]]) +- Code lens for references/implementations ([[doom-package:][xref]]) +- Highlights +- Code formatting +- Maven pom.xml project support +- Limited Gradle support +- Visual debugger ([[doom-package:][dap-mode]]) +- Test runner ([[doom-package:][dap-mode]]) +- Project explorer integration ([[doom-package:][treemacs]]) +- Integration with [[https://start.spring.io/][Spring Initializr]] ** =+meghanada= features -According to [[https://github.com/mopemope/meghanada-emacs/]] it adds +According to [[https://github.com/mopemope/meghanada-emacs/]], you get: +- Auto-update server module +- [[https://gradle.org/][Gradle]] and [[http://maven.apache.org/][Maven]] and Eclipse project support +- No need build tool's plugin +- Run build tool task +- Compile your project +- Syntax check and analyze java source ([[doom-package:][flycheck-meghanada]]) +- Support =Generic Types= +- Code completion with [[doom-package:][company-mode]] ([[doom-package:][company-meghanada]]) +- Optimize import and sort +- Jump declaration +- Run [[http://www.junit.org/][JUnit]] test (include test runner) +- Diagnostic reporting with [[doom-package:][flycheck]] ([[doom-package:][flycheck-meghanada]]) +- Show symbol's type info with [[doom-package:][eldoc]] +- Search references +- Full-featured text search -+ Auto-update server module -+ [[https://gradle.org/][Gradle]] and [[http://maven.apache.org/][Maven]] and Eclipse project support -+ No need build tool's plugin -+ Run build tool task -+ Compile your project -+ Syntax check and analyze java source (=flycheck-meghanada=) -+ Support =Generic Types= -+ Code completion with [[http://company-mode.github.io/][company-mode]] (=company-meghanada=) -+ Optimize import and sort -+ Jump declaration -+ Run [[http://www.junit.org/][JUnit]] test (include test runner) -+ Diagnostic reporting with [[http://flycheck.org/][flycheck]] (=flycheck-meghanada=) -+ Show symbol's type info with =el-doc= -+ Search references -+ Full-featured text search +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration -** =+lsp= -Install the eclipse server by executing =M-x lsp-install-server= and selecting +** [[doom-module:][+lsp]] +Install the eclipse server by executing ~M-x lsp-install-server~ and selecting =jdtls=. After that any newly opened =java= files should start the LSP server automatically. -To update the server, perform =SPC u M-x lsp-install-server=. +To update the server, perform ~SPC u M-x lsp-install-server~. Note that if you change Java version you may need to remove the LSP server and -install it again. You can do this with =M-x +lsp/uninstall-server= followed by -=M-x lsp-install-server=. +install it again. You can do this with ~M-x +lsp/uninstall-server~ followed by +~M-x lsp-install-server~. -Enable the =:tools (debugger +lsp)= module to get test runner support. +Enable the [[doom-module:][:tools debugger +lsp]] module to get test runner support. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/javascript/README.org b/modules/lang/javascript/README.org index 4272b94d0..468c716fb 100644 --- a/modules/lang/javascript/README.org +++ b/modules/lang/javascript/README.org @@ -1,146 +1,162 @@ -#+TITLE: lang/javascript -#+DATE: January 16, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang javascript +#+subtitle: all(hope(abandon(ye(who(enter(here)))))) +#+created: January 16, 2017 +#+since: 1.3 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#packages][Packages]] -- [[#prerequisites][Prerequisites]] - - [[#macos][MacOS]] - - [[#arch-linux][Arch Linux]] - - [[#opensuse][openSUSE]] -- [[#troubleshooting][Troubleshooting]] - - [[#tide-sort-completions-by-kind-isnt-respected][~tide-sort-completions-by-kind~ isn't respected]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] +* Description :unfold: +This module adds [[https://www.javascript.com/][JavaScript]] and [[https://www.typescriptlang.org/][TypeScript]] support to Doom Emacs. -* Description -This module adds JavaScript and TypeScript support. +- Code completion ([[doom-package:][tide]]) +- REPL support ([[doom-package:][nodejs-repl]]) +- Refactoring commands ([[doom-package:][js2-refactor]]) +- Syntax checking ([[doom-package:][flycheck]]) +- Browser code injection with [[doom-package:][skewer-mode]] +- Coffeescript & JSX support +- Jump-to-definitions and references support ([[doom-package:][xref]]) -+ Code completion (tide) -+ REPL support (nodejs-repl) -+ Refactoring commands (js2-refactor) -+ Syntax checking (flycheck) -+ Browser code injection with skewer-mode -+ Coffeescript & JSX support -+ Jump-to-definitions and references support (xref) +** Maintainers +- [[doom-user:][@hlissner]] -** Module Flags -+ =+lsp= Enables LangServer support for this module. You must have =:tools lsp= - enabled for this to work, as well as the langserver (e.g. - typescript-language-server) installed on your system. +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~js2-mode~, ~rjsx-mode~, JS in ~web-mode~, and + ~typescript-mode~. Requires [[doom-module:][:tools lsp]] and a langserver (supports ts-ls and + deno-ls). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. ** Packages -+ [[https://github.com/defunkt/coffee-mode][coffee-mode]] -+ [[https://github.com/mooz/js2-mode][js2-mode]] -+ [[https://github.com/felipeochoa/rjsx-mode][rjsx-mode]] -+ [[https://github.com/emacs-typescript/typescript.el][typescript-mode]] -+ [[https://github.com/magnars/js2-refactor.el][js2-refactor]] -+ [[https://github.com/mojochao/npm-mode][npm-mode]] -+ [[https://github.com/abicky/nodejs-repl.el][nodejs-repl]] -+ [[https://github.com/skeeto/skewer-mode][skewer-mode]] -+ [[https://github.com/ananthakumaran/tide][tide]] -+ [[https://github.com/NicolasPetton/xref-js2][xref-js2]]* +- [[doom-package:][js2-refactor]] +- [[doom-package:][nodejs-repl]] +- [[doom-package:][npm-mode]] +- [[doom-package:][rjsx-mode]] +- [[doom-package:][skewer-mode]] (DEPRECATED) +- [[doom-package:][tide]] +- [[doom-package:][typescript-mode]] +- [[doom-package:][xref-js2]] if [[doom-module:][:tools lookup]] -* Prerequisites -Many of this modules' plugins require ~node~ and either ~npm~ or ~yarn~ -installed. +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote -** MacOS -#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes") -brew install node -#+END_SRC +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -** Arch Linux -#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes") -sudo pacman --needed --noconfirm -S nodejs npm -#+END_SRC +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -** openSUSE -#+BEGIN_SRC sh :dir /sudo:: -sudo zypper install nodejs npm -#+END_SRC +This module requires [[https://nodejs.org/en/][NodeJS]] and one of [[https://www.npmjs.com/][NPM]] or [[https://yarnpkg.com/][Yarn]] in your =$PATH=. -* Troubleshooting -** ~tide-sort-completions-by-kind~ isn't respected -The =:completion company= module uses =company-prescient= to sort completion by -[[https://developer.mozilla.org/en-US/docs/Mozilla/Tech/Places/Frecency_algorithm][frecency]], which overrules specialized sorting provided by some company backends -(like ~company-tide~). +- MacOS: ~$ brew install node~ +- Arch Linux: ~$ pacman --needed --noconfirm -S nodejs npm~ +- openSUSE: ~$ zypper install nodejs npm~ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +~rjsx-mode~ is used for all javascript buffers. -* Appendix ** Commands -*** JS2-mode +*** rjsx-mode | command | key / ex command | description | |----------------------------------+------------------+------------------------------------------------------------| -| ~+javascript/open-repl~ | =:repl= | Open the NodeJS REPL (or send the current selection to it) | -| ~+javascript/skewer-this-buffer~ | =SPC m S= | Attaches a browser to the current buffer | +| ~+javascript/open-repl~ | ~:repl~ | Open the NodeJS REPL (or send the current selection to it) | +| ~+javascript/skewer-this-buffer~ | [[kbd:][ S]] | Attaches a browser to the current buffer | + *** Tide -| command | key / ex command | description | -|-------------------------+------------------+------------------------| -| ~tide-restart-server~ | =SPC m R= | Restart tide server | -| ~tide-reformat~ | =SPC m f= | Reformat region | -| ~tide-rename-symbol~ | =SPC m r r s= | Rename symbol at point | -| ~tide-organize-imports~ | =SPC m r o i= | Organize imports | +| command | key / ex command | description | +|-------------------------+---------------------+------------------------| +| ~tide-restart-server~ | [[kbd:][ R]] | Restart tide server | +| ~tide-reformat~ | [[kbd:][ f]] | Reformat region | +| ~tide-rename-symbol~ | [[kbd:][ r r s]] | Rename symbol at point | +| ~tide-organize-imports~ | [[kbd:][ r o i]] | Organize imports | + *** Refactoring (js2-refactor-mode) -| command | key / ex command | description | -|---------------------------------------------------+------------------+--------------------------------------------------------------------------------------------------------------------| -| ~js2r-expand-node-at-point~ | =SPC m r e e= | Expand bracketed list according to node type at point | -| ~js2r-contract-node-at-point~ | =SPC m r c c= | Contract bracketed list according to node type at point | -| ~js2r-extract-function~ | =SPC m r e f= | Extracts the marked expressions out into a new named function. | -| ~js2r-extract-method~ | =SPC m r e m= | Extracts the marked expressions out into a new named method in an object literal. | -| ~js2r-toggle-function-expression-and-declaration~ | =SPC m r t f= | Toggle between function name() {} and var name = function (); | -| ~js2r-toggle-arrow-function-and-expression~ | =SPC m r t a= | Toggle between function expression to arrow function. | -| ~js2r-toggle-function-async~ | =SPC m r t s= | Toggle between an async and a regular function. | -| ~js2r-introduce-parameter~ | =SPC m r i p= | Changes the marked expression to a parameter in a local function. | -| ~js2r-localize-parameter~ | =SPC m r l p= | Changes a parameter to a local var in a local function. | -| ~js2r-wrap-buffer-in-iife~ | =SPC m r w i= | Wraps the entire buffer in an immediately invoked function expression | -| ~js2r-inject-global-in-iife~ | =SPC m r i g= | Creates a shortcut for a marked global by injecting it in the wrapping immediately invoked function expression | -| ~js2r-add-to-globals-annotation~ | =SPC m r a g= | Creates a /*global */ annotation if it is missing, and adds the var at point to it. | -| ~js2r-extract-var~ | =SPC m r e v= | Takes a marked expression and replaces it with a var. | -| ~js2r-extract-let~ | =SPC m r e l= | Similar to extract-var but uses a let-statement. | -| ~js2r-extract-const~ | =SPC m r e c= | Similar to extract-var but uses a const-statement. | -| ~js2r-inline-var~ | =SPC m r i v= | Replaces all instances of a variable with its initial value. | -| ~js2r-rename-var~ | =SPC m r r v= | Renames the variable on point and all occurrences in its lexical scope. | -| ~js2r-var-to-this~ | =SPC m r v t= | Changes local var a to be this.a instead. | -| ~js2r-arguments-to-object~ | =SPC m r a o= | Replaces arguments to a function call with an object literal of named arguments. | -| ~js2r-ternary-to-if~ | =SPC m r 3 i= | Converts ternary operator to if-statement. | -| ~js2r-split-var-declaration~ | =SPC m r s v= | Splits a var with multiple vars declared, into several var statements. | -| ~js2r-split-string~ | =SPC m r s s= | Splits a string. | -| ~js2r-string-to-template~ | =SPC m r s t= | Converts a string into a template string. | -| ~js2r-unwrap~ | =SPC m r u w= | Replaces the parent statement with the selected region. | -| ~js2r-log-this~ | =SPC m r l t= | Adds a console.log() statement for what is at point (or region). With a prefix argument, use JSON pretty-printing. | -| ~js2r-debug-this~ | =SPC m r d t= | Adds a debug() statement for what is at point (or region). | -| ~js2r-forward-slurp~ | =SPC m r s l= | Moves the next statement into current function, if-statement, for-loop or while-loop. | -| ~js2r-forward-barf~ | =SPC m r b a= | Moves the last child out of current function, if-statement, for-loop or while-loop. | -| ~js2r-kill~ | =SPC m r k= | Kills to the end of the line, but does not cross semantic boundaries. | +| command | key / ex command | description | +|---------------------------------------------------+---------------------+--------------------------------------------------------------------------------------------------------------------| +| ~js2r-expand-node-at-point~ | [[kbd:][ r e e]] | Expand bracketed list according to node type at point | +| ~js2r-contract-node-at-point~ | [[kbd:][ r c c]] | Contract bracketed list according to node type at point | +| ~js2r-extract-function~ | [[kbd:][ r e f]] | Extracts the marked expressions out into a new named function. | +| ~js2r-extract-method~ | [[kbd:][ r e m]] | Extracts the marked expressions out into a new named method in an object literal. | +| ~js2r-toggle-function-expression-and-declaration~ | [[kbd:][ r t f]] | Toggle between function name() {} and var name = function (); | +| ~js2r-toggle-arrow-function-and-expression~ | [[kbd:][ r t a]] | Toggle between function expression to arrow function. | +| ~js2r-toggle-function-async~ | [[kbd:][ r t s]] | Toggle between an async and a regular function. | +| ~js2r-introduce-parameter~ | [[kbd:][ r i p]] | Changes the marked expression to a parameter in a local function. | +| ~js2r-localize-parameter~ | [[kbd:][ r l p]] | Changes a parameter to a local var in a local function. | +| ~js2r-wrap-buffer-in-iife~ | [[kbd:][ r w i]] | Wraps the entire buffer in an immediately invoked function expression | +| ~js2r-inject-global-in-iife~ | [[kbd:][ r i g]] | Creates a shortcut for a marked global by injecting it in the wrapping immediately invoked function expression | +| ~js2r-add-to-globals-annotation~ | [[kbd:][ r a g]] | Creates a /*global */ annotation if it is missing, and adds the var at point to it. | +| ~js2r-extract-var~ | [[kbd:][ r e v]] | Takes a marked expression and replaces it with a var. | +| ~js2r-extract-let~ | [[kbd:][ r e l]] | Similar to extract-var but uses a let-statement. | +| ~js2r-extract-const~ | [[kbd:][ r e c]] | Similar to extract-var but uses a const-statement. | +| ~js2r-inline-var~ | [[kbd:][ r i v]] | Replaces all instances of a variable with its initial value. | +| ~js2r-rename-var~ | [[kbd:][ r r v]] | Renames the variable on point and all occurrences in its lexical scope. | +| ~js2r-var-to-this~ | [[kbd:][ r v t]] | Changes local var a to be this.a instead. | +| ~js2r-arguments-to-object~ | [[kbd:][ r a o]] | Replaces arguments to a function call with an object literal of named arguments. | +| ~js2r-ternary-to-if~ | [[kbd:][ r 3 i]] | Converts ternary operator to if-statement. | +| ~js2r-split-var-declaration~ | [[kbd:][ r s v]] | Splits a var with multiple vars declared, into several var statements. | +| ~js2r-split-string~ | [[kbd:][ r s s]] | Splits a string. | +| ~js2r-string-to-template~ | [[kbd:][ r s t]] | Converts a string into a template string. | +| ~js2r-unwrap~ | [[kbd:][ r u w]] | Replaces the parent statement with the selected region. | +| ~js2r-log-this~ | [[kbd:][ r l t]] | Adds a console.log() statement for what is at point (or region). With a prefix argument, use JSON pretty-printing. | +| ~js2r-debug-this~ | [[kbd:][ r d t]] | Adds a debug() statement for what is at point (or region). | +| ~js2r-forward-slurp~ | [[kbd:][ r s l]] | Moves the next statement into current function, if-statement, for-loop or while-loop. | +| ~js2r-forward-barf~ | [[kbd:][ r b a]] | Moves the last child out of current function, if-statement, for-loop or while-loop. | +| ~js2r-kill~ | [[kbd:][ r k]] | Kills to the end of the line, but does not cross semantic boundaries. | + *** skewer-mode **** general -| command | key / ex command | description | -|-------------------------------+------------------+---------------------------------------| -| ~skewer-eval-last-expression~ | =SPC m s E= | Evaluate last expression | -| ~skewer-eval-defun~ | =SPC m s e= | Evaluate function definition at point | -| ~skewer-load-buffer~ | =SPC m s f= | Load buffer into REPL | +| command | key / ex command | description | +|-------------------------------+-------------------+---------------------------------------| +| ~skewer-eval-last-expression~ | [[kbd:][ s E]] | Evaluate last expression | +| ~skewer-eval-defun~ | [[kbd:][ s e]] | Evaluate function definition at point | +| ~skewer-load-buffer~ | [[kbd:][ s f]] | Load buffer into REPL | + **** css -| command | key / ex command | description | -|---------------------------------------+------------------+-------------------------------| -| ~skewer-css-eval-current-declaration~ | =SPC m s e= | Evaluate declaration at point | -| ~skewer-css-eval-current-rule~ | =SPC m s r= | Evaluate rule at point | -| ~skewer-css-eval-buffer~ | =SPC m s b= | Evaluate buffer | -| ~skewer-css-clear-all~ | =SPC m s c= | Clear all rules | +| command | key / ex command | description | +|---------------------------------------+-------------------+-------------------------------| +| ~skewer-css-eval-current-declaration~ | [[kbd:][ s e]] | Evaluate declaration at point | +| ~skewer-css-eval-current-rule~ | [[kbd:][ s r]] | Evaluate rule at point | +| ~skewer-css-eval-buffer~ | [[kbd:][ s b]] | Evaluate buffer | +| ~skewer-css-clear-all~ | [[kbd:][ s c]] | Clear all rules | + **** html -| command | key / ex command | description | -|------------------------+------------------+-----------------------| -| ~skewer-html-eval-tag~ | =SPC m s e= | Evaluate tag at point | +| command | key / ex command | description | +|------------------------+-------------------+-----------------------| +| ~skewer-html-eval-tag~ | [[kbd:][ s e]] | Evaluate tag at point | + *** npm-mode -| command | key / ex command | description | -|---------------------------------+------------------+------------------------------------------------------------------| -| ~npm-mode-npm-init~ | =SPC m n n= | Initialize npm project | -| ~npm-mode-npm-install~ | =SPC m n i= | Install npm package | -| ~npm-mode-npm-install-save~ | =SPC m n s= | Install npm package and save to package.json | -| ~npm-mode-npm-install-save-dev~ | =SPC m n d= | Install npm package and save to package.json as a dev dependency | -| ~npm-mode-npm-uninstall~ | =SPC m n u= | Uninstall npm package | -| ~npm-mode-npm-list~ | =SPC m n l= | List npm packages | -| ~npm-mode-npm-run~ | =SPC m n r= | Run npm task | -| ~npm-mode-visit-project-file~ | =SPC m n v= | Find file in npm project | +| command | key / ex command | description | +|---------------------------------+-------------------+------------------------------------------------------------------| +| ~npm-mode-npm-init~ | [[kbd:][ n n]] | Initialize npm project | +| ~npm-mode-npm-install~ | [[kbd:][ n i]] | Install npm package | +| ~npm-mode-npm-install-save~ | [[kbd:][ n s]] | Install npm package and save to package.json | +| ~npm-mode-npm-install-save-dev~ | [[kbd:][ n d]] | Install npm package and save to package.json as a dev dependency | +| ~npm-mode-npm-uninstall~ | [[kbd:][ n u]] | Uninstall npm package | +| ~npm-mode-npm-list~ | [[kbd:][ n l]] | List npm packages | +| ~npm-mode-npm-run~ | [[kbd:][ n r]] | Run npm task | +| ~npm-mode-visit-project-file~ | [[kbd:][ n v]] | Find file in npm project | + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/json/README.org b/modules/lang/json/README.org index e3255d43f..ad7ac98c9 100644 --- a/modules/lang/json/README.org +++ b/modules/lang/json/README.org @@ -1,40 +1,57 @@ -#+TITLE: lang/json -#+DATE: April 23, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang json +#+subtitle: At least it ain't XML +#+created: April 23, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This module provides JSON support. +* Description :unfold: +This module adds [[https://www.json.org/json-en.html][JSON]] support to Doom Emacs. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+lsp= Enable integration with LSP servers, if one is available. Requires the - =:tools lsp= module to be enabled. +** Module flags +- +lsp :: + Enable LSP support for ~json-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/vscode-langservers/vscode-json-languageserver][vscode-json-languageserver]]). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -** Plugins -+ [[https://github.com/joshwnj/json-mode][json-mode]] -+ [[https://github.com/Sterlingg/json-snatcher][json-snatcher]] +** Packages +- [[doom-package:][counsel-jq]] if [[doom-module:][:completion ivy]] +- [[doom-package:][json-mode]] +- [[doom-package:][json-snatcher]] -* Prerequisites -This module has no prerequisites. +** Hacks +/No hacks documented for this module./ -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration -# How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/julia/README.org b/modules/lang/julia/README.org index d3b5b585d..c13ec7c4c 100644 --- a/modules/lang/julia/README.org +++ b/modules/lang/julia/README.org @@ -1,109 +1,131 @@ -#+TITLE: lang/julia -#+DATE: April 8, 2020 -#+SINCE: v1.3 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang julia +#+subtitle: A better, faster MATLAB +#+created: April 08, 2020 +#+since: 1.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#language-server][Language Server]] - - [[#lsp-julia][~lsp-julia~]] - - [[#eglot-jl][~eglot-jl~]] -- [[#features][Features]] - - [[#language-server-1][Language Server]] -- [[#configuration][Configuration]] - - [[#change-the-default-environment-for-the-julia-language-server][Change the default environment for the Julia language server]] - -* Description +* Description :unfold: This module adds support for [[https://julialang.org/][the Julia language]] to Doom Emacs. -+ Syntax highlighting and latex symbols from ~julia-mode~ -+ REPL integration from ~julia-repl~ -+ Code completion and syntax checking, requires ~:tools lsp~ and ~+lsp~ +- Syntax highlighting and latex symbols from [[doom-package:][julia-mode]] +- REPL integration from [[doom-package:][julia-repl]] +- Code completion and syntax checking, requires [[doom-module:][:tools lsp]] and [[doom-module:][+lsp]] -** Module Flags -+ =+lsp= Enable LSP server support. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/JuliaEditorSupport/julia-emacs/][julia-mode]] -+ [[https://github.com/tpapp/julia-repl][julia-repl]] -+ =+lsp= and =:tools lsp= - + [[https://github.com/non-jedi/lsp-julia][lsp-julia]] - + [[https://github.com/emacs-lsp/lsp-mode][lsp]] -+ =+lsp= and =:tools lsp +eglot= - + [[https://github.com/non-jedi/eglot-jl][eglot-jl]] - + [[https://github.com/joaotavora/eglot][eglot]] +** Module flags +- +lsp :: + Enable LSP support for ~julia-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports LanguageServer.jl). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -* Prerequisites -This module requires =julia= and an language server if =+lsp= is enabled. +** Packages +- [[doom-package:][julia-mode]] +- [[doom-package:][julia-repl]] +- if [[doom-package:][+lsp]] + - if [[doom-module:][:tools lsp]] + - [[doom-package:][lsp-julia]] + - [[doom-package:][lsp]] + - if [[doom-module:][:tools lsp +eglot]] + - [[doom-package:][eglot-jl]] + - [[doom-package:][eglot]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires [[https://julialang.org/][Julia]] and an language server if [[doom-module:][+lsp]] is enabled. ** Language Server -~+lsp~ requires ~LanguageServer.jl~ and ~SymbolServer.jl~. The =lsp-julia= and -=eglot-jl= packages both come bundled with their own versions of these servers, +[[doom-module:][+lsp]] requires ~LanguageServer.jl~ and ~SymbolServer.jl~. The [[doom-package:][lsp-julia]] and +[[doom-package:][eglot-jl]] packages both come bundled with their own versions of these servers, which is used by default. If you're happy with that, no further configuration is necessary. However, to use your own installation you will need to install then configure them. To install them, execute these commands in a Julia REPL: - -#+BEGIN_SRC julia +#+begin_src julia using Pkg Pkg.add("LanguageServer") Pkg.add("SymbolServer") -#+END_SRC +#+end_src -Then configure =lsp-julia= or =eglot-jl= depending on whether you have enabled -=:tools lsp= or =:tools (lsp +eglot)=, respectively: +Then configure [[doom-package:][lsp-julia]] or [[doom-package:][eglot-jl]] depending on whether you have enabled +[[doom-module:][:tools lsp]] or [[doom-module:][:tools lsp +eglot]], respectively: -*** ~lsp-julia~ -To instruct =lsp-julia= not to use the built-in package: - -#+BEGIN_SRC elisp -;; ~/.doom.d/config.el +*** =lsp-julia= +To instruct [[doom-package:][lsp-julia]] not to use the built-in package: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq lsp-julia-package-dir nil) -#+END_SRC +#+end_src -To find your installation of ~LanguageServer.jl~, ~eglot-jl~ needs to know the -environment in which it is installed. This is set to v1.0 by default as it is +To find your installation of ~LanguageServer.jl~, [[doom-package:][lsp-julia]] needs to know the +environment in which it is installed. This is set to v1.6 by default as it is the current LTS: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el +(after! lsp-julia + (setq lsp-julia-default-environment "~/.julia/environments/v1.6")) +#+end_src -#+BEGIN_SRC elisp -(setq lsp-julia-default-environment "~/.julia/environments/v1.0") -#+END_SRC - -*** ~eglot-jl~ -To find your installation of ~LanguageServer.jl~, ~eglot-jl~ must know the -environment in which it is installed. This is set to v1.0 by default as it is +*** =eglot-jl= +To find your installation of ~LanguageServer.jl~, [[doom-package:][eglot-jl]] must know the +environment in which it is installed. This is set to v1.6 by default as it is the current LTS: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el +(setq eglot-jl-language-server-project "~/.julia/environments/v1.6") +#+end_src -#+BEGIN_SRC elisp -;; ~/.doom.d/config.el -(setq eglot-jl-language-server-project "~/.julia/environments/v1.0") -#+END_SRC - -But to let ~eglot-jl~ use the environment bundled with it, set it to +But to let [[doom-package:][eglot-jl]] use the environment bundled with it, set it to ~eglot-jl-base~ instead: - -#+BEGIN_SRC elisp -;; ~/.doom.d/config.el +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (after! eglot-jl (setq eglot-jl-language-server-project eglot-jl-base)) -#+END_SRC +#+end_src + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** Language Server -~+lsp~ adds code completion, syntax checking, formatting and other ~lsp-mode~ or -~eglot~ features. It requires ~LanguageServer.jl~, the installation of which is +[[doom-module:][+lsp]] adds code completion, syntax checking, formatting and other [[doom-package:][lsp-mode]] or +[[doom-package:][eglot]] features. It requires ~LanguageServer.jl~, the installation of which is described above. -* Configuration -** Change the default environment for the Julia language server -~lsp-julia~ requires a variable be set for the Julia environment. This is set to -v1.0 by default as it is the current LTS. +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -#+BEGIN_SRC elisp -;; ~/.doom.d/config.el -(setq lsp-julia-default-environment "~/.julia/environments/v1.0") -#+END_SRC +** Change the default environment for the Julia language server +[[doom-package:][lsp-julia]] requires a variable be set for the Julia environment. This is set to +v1.6 by default as it is the current LTS: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el +(after! lsp-julia + (setq lsp-julia-default-environment "~/.julia/environments/v1.6")) +#+end_src + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/kotlin/README.org b/modules/lang/kotlin/README.org index 00cce96db..93610a86c 100644 --- a/modules/lang/kotlin/README.org +++ b/modules/lang/kotlin/README.org @@ -1,36 +1,55 @@ -#+TITLE: lang/kotlin -#+DATE: March 28, 2019 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang kotlin +#+subtitle: A Java(Script) that won't depress you +#+created: March 28, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module adds [[https://kotlinlang.org/][Kotlin]] support to Doom Emacs. -* Description -This module adds Kotlin support to Emacs. +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+lsp= Enables integration with [[https://github.com/emacs-lsp/lsp-mode][kotlin-language-server]]. This requires the - =:tools lsp= module. +** Module flags +- +lsp :: + Enable LSP support for ~kotlin-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/emacs-lsp/lsp-mode][kotlin-language-server]]). -** Plugins -+ kotlin-mode -+ flycheck-kotlin +** Packages +- [[doom-package:][flycheck-kotlin]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][kotlin-mode]] -* Prerequisites -TODO +** Hacks +/No hacks documented for this module./ -* Features -TODO +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Configuration -TODO +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote + πŸ”¨ /This module's prerequisites are not documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -TODO +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/latex/README.org b/modules/lang/latex/README.org index f42a3f01d..b0409bcdf 100644 --- a/modules/lang/latex/README.org +++ b/modules/lang/latex/README.org @@ -1,98 +1,112 @@ -#+TITLE: lang/latex -#+DATE: January 16, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang latex +#+subtitle: Writing papers in Emacs has never been so fun +#+created: January 16, 2017 +#+since: 1.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#ubuntu][Ubuntu]] - - [[#arch-linux][Arch Linux]] - - [[#macos][macOS]] - - [[#nixos][NixOS]] -- [[#features][Features]] -- [[#customization][Customization]] - - [[#specifying-the-location-of-a-bibtex-file--corresponding-pdfs][Specifying the location of a bibtex file & corresponding PDFs]] - - [[#changing-the-pdfs-viewer][Changing the PDFs viewer]] - - [[#using-cdlatexs-snippets-despite-having-yasnippet][Using cdlatex's snippets despite having yasnippet]] - -* Description +* Description :unfold: Provide a helping hand when working with LaTeX documents. -+ Sane defaults -+ Fontification of many popular commands -+ Pretty indentation of wrapped lines using the ~adaptive-wrap~ package -+ Spell checking with ~flycheck~ -+ Change PDF viewer to Okular or ~latex-preview-pane~ -+ Bibtex editor -+ Autocompletion using ~company-mode~ -+ Compile your .tex code only once using LatexMk +- Sane defaults +- Fontification of many popular commands +- Pretty indentation of wrapped lines using the [[doom-package:][adaptive-wrap]] package +- Spell checking with [[doom-package:][flycheck]] +- Change PDF viewer to Okular or [[doom-package:][latex-preview-pane]] +- Bibtex editor +- Autocompletion using [[doom-package:][company-mode]] +- Compile your =.tex= code only once using LatexMk -** Module Flags -+ =+latexmk= Use LatexMk instead of LaTeX to compile documents. -+ =+cdlatex= Enable [[https://github.com/cdominik/cdlatex][cdlatex]] for fast math insertion. -+ =+lsp= Start LSP automatically in `tex-mode-hook`. This requires the =:tools - lsp= module. Supported servers are `digestif` and `TexLab`. -+ =+fold= Use TeX-fold (from auctex) to fold LaTeX macros to unicode, and make - folding hook-based and less manual. +** Maintainers +- [[doom-user:][@tecosaur]] +- [[doom-user:][@ymarco]] -** Plugins -+ [[http://www.gnu.org/software/auctex/][auctex]] -+ [[http://elpa.gnu.org/packages/adaptive-wrap.html][adaptive-wrap]] -+ [[https://github.com/iyefrat/evil-tex][evil-tex]] (when =:editor evil +everywhere=) -+ [[https://github.com/jsinglet/latex-preview-pane][latex-preview-pane]] -+ [[https://github.com/tom-tan/auctex-latexmk][auctex-latexmk]]* -+ [[https://github.com/alexeyr/company-auctex][company-auctex]]* -+ [[https://github.com/TheBB/company-reftex][company-reftex]]* -+ [[https://github.com/vspinu/company-math][company-math]]* -+ [[https://github.com/cdominik/cdlatex][cdlatex]] (=+cdlatex=) +[[doom-contrib-maintainer:][Become a maintainer?]] -* Prerequisites -You will need ghostscript and a latex compiler. All this is provided by -the =texlive= bundle, available through many OS package managers. +** Module flags +- +cdlatex :: + Enable [[doom-package:][cdlatex]] for fast math insertion. +- +fold :: + Use TeX-fold (from [[doom-package:][auctex]]) to fold LaTeX macros to unicode, and make folding + hook-based and less manual. +- +latexmk :: + Use LatexMk instead of LaTeX to compile documents. +- +lsp :: + Enable LSP support in latex buffers. Requires [[doom-module:][:tools lsp]] and a langserver + (supports digestif and TexLab). + +** Packages +- [[doom-package:][adaptive-wrap]] +- [[doom-package:][auctex]] +- [[doom-package:][auctex-latexmk]] if [[doom-module:][+latexmk]] +- [[doom-package:][cdlatex]] if [[doom-module:][+cdlatex]] +- [[doom-package:][evil-tex]] if [[doom-module:][:editor evil +everywhere]] +- [[doom-package:][latex-preview-pane]] +- if [[doom-module:][:completion company]] + - [[doom-package:][company-auctex]] + - [[doom-package:][company-math]] + - [[doom-package:][company-reftex]] + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires ghostscript and a latex compiler. These are provided by the +=texlive= bundle, available through many OS package managers. + +#+begin_quote + 🚧 Ghostscript <= 9.27 is [[/auctex/manual/preview-latex/No-images-are-displayed-with-gs-9_002e27-and-earlier.html][reportedly buggy]] and doesn't work with auctex's math + previews. (You can check you ghostscript version with ~$ gs --version~.) + Most package managers already have newer versions, but if not you might have + to build gs from source. +#+end_quote -Ghostscript <= 9.27 is [[https://www.gnu.org/software/auctex/manual/preview-latex/No-images-are-displayed-with-gs-9_002e27-and-earlier.html][reported buggy]] and doesn't work with auctex's math -previews. (You can check you ghostscript version with ~gs --version~.) Most -package managers already have newer versions, but if not you might have to build -gs from source. ** Ubuntu -#+BEGIN_SRC sh +#+begin_src sh apt-get install texlive -#+END_SRC +#+end_src ** Arch Linux -#+BEGIN_SRC sh +#+begin_src sh pacman -S texlive-core -#+END_SRC +#+end_src ** TODO macOS -#+BEGIN_SRC sh +#+begin_src sh brew install --cask basictex # If the above doesn't work, then brew install --cask mactex # WARNING: large 4gb download! -#+END_SRC +#+end_src #+begin_quote -This has not been verified. + πŸ”¨ This has not been verified. #+end_quote ** NixOS -#+BEGIN_SRC nix +#+begin_src nix environment.systemPackages = [ pkgs.texlive.combined.scheme-medium ]; -#+END_SRC +#+end_src -* TODO Features +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* Customization +* Configuration ** Specifying the location of a bibtex file & corresponding PDFs -Reftex has a variable that allow you to -specify where it should find your bibliography file(s): - -#+BEGIN_SRC emacs-lisp +Reftex has a variable that allow you to specify where it should find your +bibliography file(s): +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq reftex-default-bibliography "/your/bib/file.bib") -#+END_SRC +#+end_src ** Changing the PDFs viewer This module provides integration for four supported pdf viewers. They are @@ -102,30 +116,41 @@ This module provides integration for four supported pdf viewers. They are + Sumatra PDF + Zathura + Okular -+ pdf-tools (requires =:tools pdf= module) ++ pdf-tools (requires [[doom-module:][:tools pdf]] module) They are searched for in this order. See ~+latex-viewers~ to change the order, or remove tools from the search altogether. If you want to exclusively use one tool, for instance: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq +latex-viewers '(zathura)) -#+END_SRC +#+end_src If none of these tools are found, ~latex-preview-pane~ (uses ~DocView~ in Emacs) is used as a fallback. You can use this exclusively by setting ~+latex-viewers~ to ~nil~. ** Using cdlatex's snippets despite having yasnippet -cdlatex has a snippet insertion capability which is disabled in favor of -yasnippet when using ~:editor snippets~. If you still wanna use it, simply rebind -the ~TAB~ key for cdlatex, which takes care of snippet-related stuff: - -#+BEGIN_SRC emacs-lisp +[[doom-package:][cdlatex]] has a snippet insertion capability which is disabled in favor of +[[doom-package:][yasnippet]] when using [[doom-module:][:editor snippets]]. If you still wanna use it, simply rebind +the [[kbd:][TAB]] key for cdlatex, which takes care of snippet-related stuff: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (map! :map cdlatex-mode-map - :i "TAB" #'cdlatex-tab) -#+END_SRC + :i "TAB" #'cdlatex-tab) +#+end_src This would favor yasnippet's expansion and cursor movement over cdlatex's expansion and movement, but that shouldn't matter if you're not using yasnippet in latex buffers. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/lean/README.org b/modules/lang/lean/README.org new file mode 100644 index 000000000..37541a1f6 --- /dev/null +++ b/modules/lang/lean/README.org @@ -0,0 +1,55 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang lean +#+subtitle: For folks with too much to prove +#+created: September 10, 2019 +#+since: 21.12.0 (#1759) + +* Description :unfold: +This module adds support for the [[https://leanprover.github.io/about/][Lean programming language]] to Doom Emacs. + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][lean-mode]] +- [[doom-package:][company-lean]] if [[doom-module:][:completion company]] + +** TODO Hacks +#+begin_quote +πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote +πŸ”¨ /This module's prerequisites are not documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/ledger/README.org b/modules/lang/ledger/README.org index e51f652c8..c3845e669 100644 --- a/modules/lang/ledger/README.org +++ b/modules/lang/ledger/README.org @@ -1,56 +1,74 @@ -#+TITLE: lang/ledger -#+DATE: October 13, 2019 -#+SINCE: v2.0.4 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang ledger +#+subtitle: Be audit you can be +#+created: September 09, 2017 +#+since: 2.0.6 (#194) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - -* Description +* Description :unfold: This module adds support for [[https://www.ledger-cli.org/][ledger]] files. Ledger is a command line double-entry accounting system that works with simple text files holding transactions in the following format: - -#+BEGIN_SRC ledger +#+begin_src ledger 2015/10/12 Exxon Expenses:Auto:Gas $10.00 Liabilities:MasterCard $-10.00 -#+END_SRC +#+end_src This modules enables the following features: -+ Syntax and indentation support for ledger files -+ Add, edit, and delete transactions -+ Generate reports -+ Schedule transactions -+ Sort transactions -+ Display statistics about transactions -+ Display balance up to a point +- Syntax and indentation support for ledger files +- Add, edit, and delete transactions +- Generate reports +- Schedule transactions +- Sort transactions +- Display statistics about transactions +- Display balance up to a point -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/purcell/flycheck-ledger][flycheck-ledger]] -+ [[https://github.com/atheriel/evil-ledger][evil-ledger]] +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][evil-ledger]] if [[doom-module:][:editor evil +everywhere]] +- [[doom-package:][flycheck-ledger]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][ledger-mode]] ** Hacks -This module sets ~ledger-clear-whole-transactions~ to ~t~ (default value is -~nil~). This results in ~ledger-toggle-current~ toggling the clear status of the -whole transaction instead of toggling just the current posting. +- This module sets ~ledger-clear-whole-transactions~ to ~t~ (default value is + ~nil~). This results in ~ledger-toggle-current~ toggling the clear status of + the whole transaction instead of toggling just the current posting. -* Prerequisites -In order for ~flycheck-ledger~ to work and to be able to generate reports you -will need to install [[https://www.ledger-cli.org/][ledger]]. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* TODO Features -An in-depth list of features, how to use them, and their dependencies. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires [[https://www.ledger-cli.org/][ledger]] to syntax check and generate reports from your +ledgers. + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration Please refer to ~ledger-mode~'s documentation for information on how to -configure it. You can do so within emacs with =C-h i= +configure it. You can do so within emacs with [[kbd:][C-h i]] + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/lua/README.org b/modules/lang/lua/README.org index ddf2a5577..91663670f 100644 --- a/modules/lang/lua/README.org +++ b/modules/lang/lua/README.org @@ -1,57 +1,66 @@ -#+TITLE: lang/lua -#+DATE: Jun 3, 2020 -#+SINCE: v3.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang lua +#+subtitle: One-based indices? one-based indices +#+created: Jun 03, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#language-server-protocol-servers][Language Server Protocol servers]] - - [[#lsp-mode][LSP-mode]] - - [[#eglot][Eglot]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - - [[#install-lua-language-server][Install lua-language-server]] +* Description :unfold: +This module adds Lua support to Doom Emacs. -* Description -Adds Lua support to Doom Emacs -# A summary of what this module does. - -+ REPL -+ Love2D specific functions -+ Moonscript support +- REPL +- Love2D specific functions +- Moonscript support +- Fennel support ** Maintainers -This module has no dedicated maintainers. +- [[doom-user:][@hlissner]] -** Module Flags -+ =+moonscript= Moonscript language support -+ =+fennel= Fennel language support -+ =+lsp= Language Server Protocol support +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -# A list of linked plugins -+ [[https://github.com/immerrr/lua-mode][lua-mode]] -+ [[https://github.com/k2052/moonscript-mode][moonscript-mode]] (=+moonscript=) -+ [[https://gitlab.com/technomancy/fennel-mode][fennel-mode]] (=+fennel=) +** Module flags +- +fennel :: + Enable support for the Fennel language. +- +lsp :: + Enable LSP support for ~lua-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports EmmyLua, lua-language-server, and lua-lsp). +- +moonscript :: + Enable support for the Moonscript language. + +** Packages +- [[doom-package:][company-lua]] if [[doom-module:][:completion company]] +- [[doom-package:][fennel-mode]] if [[doom-module:][+fennel]] +- [[doom-package:][lua-mode]] +- if [[doom-module:][+moonscript]] + - [[doom-package:][flycheck-moonscript]] if [[doom-module:][:checkers syntax]] + - [[doom-package:][moonscript-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires Lua 5.1+ for most of its capabilities and, optionally, the +fennel and moonscript transpilers. An LSP server is also required for LSP +support. -* Prerequisites ** Language Server Protocol servers -LSP server support depends on which flavor of the =:tools lsp= module you have -installed (Eglot or LSP-mode). +LSP server support depends on which flavor of the [[doom-module:][:tools lsp]] module you have +installed ([[doom-package:][eglot]] or [[doom-package:][lsp-mode]]). *** LSP-mode Three servers are supported, ordered from highest to lowest priority: - -+ [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua-LanguageServer]] :: Must be in =~/.emacs.d/.local/etc/lsp/EmmyLua-LS-all.jar=. See ~lsp-clients-emmy-lua-jar-path~ variable to change this. -+ [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in - =~/.config/emacs/.local/etc/lsp/lua-language-server/=. See +- [[https://github.com/EmmyLua/EmmyLua-LanguageServer][EmmyLua-LanguageServer]] :: Must be in + =$EMACSDIR/.local/etc/lsp/EmmyLua-LS-all.jar=. See + ~lsp-clients-emmy-lua-jar-path~ variable to change this. +- [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in + =$EMACSDIR/.local/etc/lsp/lua-language-server/=. See ~lsp-clients-lua-language-server-bin~ variable to change this. -+ [[https://github.com/Alloyed/lua-lsp][lua-lsp]] :: Must be available in =~/.luarocks/bin/lua-lsp=. See +- [[https://github.com/Alloyed/lua-lsp][lua-lsp]] :: Must be available in =~/.luarocks/bin/lua-lsp=. See ~lsp-clients-lua-lsp-server-install-dir~ variable to change this. [[https://emacs-lsp.github.io/lsp-mode/page/lsp-emmy-lua/][LSP-mode documentation]] has more information about setting up the server and the @@ -59,20 +68,35 @@ configuration variables correctly. *** Eglot Eglot currently only supports one of the above servers out of the box: - + [[https://github.com/sumneko/lua-language-server][Sumneko language server]] (lua-language-server) :: Must be in - =~/.config/emacs/.local/etc/lsp/lua-language-server/=. See - ~+lua-lsp-dir~ variable to change this. + =$EMACSDIR/.local/etc/lsp/lua-language-server/=. See ~+lua-lsp-dir~ variable + to change this. -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* Configuration -- lua-lsp-dir :: This must be set when using =+lsp= and using - [[https://github.com/sumneko/lua-language-server][lua-language-server]]. This controls where the repository has been cloned and - built to finish the configuration of the server. +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- lua-lsp-dir :: This must be set when using [[doom-module:][+lsp]] and using [[https://github.com/sumneko/lua-language-server][lua-language-server]]. + This controls where the repository has been cloned and built to finish the + configuration of the server. * Troubleshooting +[[doom-report:][Report an issue?]] + ** Install lua-language-server A [[https://github.com/sumneko/lua-language-server/issues/60][catch-all issue]] has been created to gather help for installing lua-language-server on non-VSCode platforms. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/markdown/README.org b/modules/lang/markdown/README.org index 810c7eb4c..59f50245b 100644 --- a/modules/lang/markdown/README.org +++ b/modules/lang/markdown/README.org @@ -1,26 +1,10 @@ -#+TITLE: lang/markdown -#+DATE: February 19, 2017 -#+SINCE: 2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang markdown +#+subtitle: Write docs for people to ignore +#+created: February 19, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] - - [[#linters][Linters]] - - [[#markdown-preview][Markdown preview]] - - [[#markedjs][MarkedJS]] - - [[#pandoc][Pandoc]] - - [[#markdown][Markdown]] - - [[#multimarkdown][MultiMarkdown]] -- [[#features][Features]] - - [[#markdown-preview-1][Markdown preview]] -- [[#configuration][Configuration]] - - [[#changing-how-markdown-is-compiled][Changing how markdown is compiled]] - -* Description +* Description :unfold: This module provides Markdown support for Emacs. #+begin_quote @@ -30,82 +14,97 @@ to structurally valid XHTML (or HTML). Thus, β€œMarkdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. -See the Syntax page for details pertaining to Markdown’s formatting syntax. You +See the Syntax page for details pertaining to Markdown's formatting syntax. You can try it out, right now, using the online Dingus. -The overriding design goal for Markdown’s formatting syntax is to make it as +The overriding design goal for Markdown's formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be -publishable as-is, as plain text, without looking like it’s been marked up with -tags or formatting instructions. While Markdown’s syntax has been influenced by +publishable as-is, as plain text, without looking like it's been marked up with +tags or formatting instructions. While Markdown's syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration -for Markdown’s syntax is the format of plain text email. -- John Gruber +for Markdown's syntax is the format of plain text email. -- John Gruber #+end_quote -** Module Flags -+ =+grip= Enables [[https://github.com/seagle0128/grip-mode][grip support]] (on = p=), to provide live - github-style previews of your markdown (or org) files. +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ markdown-mode -+ markdown-toc +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +grip :: + Enable [[https://github.com/seagle0128/grip-mode][grip support]] (on [[kbd:][ p]]), to provide live github-style + previews of your markdown (or org) files. + +** Packages +- [[doom-package:][edit-indirect]] +- [[doom-package:][evil-markdown]] if [[doom-module:][:editor evil +everywhere]] +- [[doom-package:][grip-mode]] if [[doom-module:][+grip]] +- [[doom-package:][markdown-mode]] +- [[doom-package:][markdown-toc]] ** Hacks -+ Flyspell has been configured not to spell check in code blocks, links, HTML +- [[doom-package:][flyspell]] has been configured not to spell check in code blocks, links, HTML tags or references. -* Prerequisites -This module has two soft dependencies: a linter and a compiler (for previewing -markdown). +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- A linter (requires [[doom-module:][:checkers syntax]]) +- A markdown compiler, for previewing Markdown ** Linters Out of the box, flycheck recognizes these checkers for markdown-mode and gfm-mode: -+ Markdown-specific - + [[https://github.com/DavidAnson/markdownlint][markdownlint]] (~npm install markdownlint~) - + [[https://github.com/markdownlint/markdownlint][mdl]] (~gem install mdl~) -+ General (natural language) - + [[http://proselint.com/][proselint]] - - ~pip install proselint~ +- Markdown-specific + - [[https://github.com/DavidAnson/markdownlint][markdownlint]] (~$ npm install markdownlint~) + - [[https://github.com/markdownlint/markdownlint][mdl]] (~$ gem install mdl~) +- General (natural language) + - [[http://proselint.com/][proselint]] + - ~$ pip install proselint~ - Or through your OS package manager - - MacOS: ~brew install proselint~ - - Arch Linux: ~pacman -S proselint~ - + [[https://github.com/textlint/textlint][textlint]] (~npm install textlint~) + - MacOS: ~$ brew install proselint~ + - Arch Linux: ~$ pacman -S proselint~ + - [[https://github.com/textlint/textlint][textlint]] (~$ npm install textlint~) -** Markdown preview +** Markdown compiler This module requires a markdown compiler in order for ~markdown-preview~ to work. It will recognize and use one of the following executables, in this order (you only need one): -+ [[https://github.com/markedjs/marked][markedjs]]: a markdown compiler "built for speed" -+ [[https://github.com/jgm/pandoc][pandoc]]: the universal markup transpiler -+ [[http://pell.portland.or.us/~orc/Code/discount/][markdown]]: there are various flavors of this compiler. This module will look +- [[https://github.com/markedjs/marked][markedjs]]: a markdown compiler "built for speed" +- [[https://github.com/jgm/pandoc][pandoc]]: the universal markup transpiler +- [[http://pell.portland.or.us/~orc/Code/discount/][markdown]]: there are various flavors of this compiler. This module will look for these two: - + John Gruber's [[https://daringfireball.net/projects/markdown/][original perl script]] - + The C implementation called [[http://pell.portland.or.us/~orc/Code/discount/][discount]], by David Parsons -+ [[https://fletcher.github.io/MultiMarkdown-6/][multimarkdown]]: a compiler for a language that is a superset of Markdown, with + - John Gruber's [[https://daringfireball.net/projects/markdown/][original perl script]] + - The C implementation called [[http://pell.portland.or.us/~orc/Code/discount/][discount]], by David Parsons +- [[https://fletcher.github.io/MultiMarkdown-6/][multimarkdown]]: a compiler for a language that is a superset of Markdown, with additional output formats and features. *** MarkedJS Not to be confused with [[https://marked2app.com/][the Marked 2 app]], marked is an npm package: - -#+BEGIN_SRC sh +#+begin_src sh npm install -g marked -#+END_SRC +#+end_src *** Pandoc Pandoc is the universal markup transpiler. It should be available through your system package manager. For example: -+ MacOS: ~brew install pandoc~ -+ Arch Linux: ~pacman -S pandoc~ ++ MacOS: ~$ brew install pandoc~ ++ Arch Linux: ~$ pacman -S pandoc~ *** Markdown The C implementation of Markdown.pl, called =discount=, is available through your OS's package manager: -+ MacOS: ~brew install discount~ -+ Arch Linux: ~pacman -S discount~ ++ MacOS: ~$ brew install discount~ ++ Arch Linux: ~$ pacman -S discount~ The original perl script that discount is inspired from can be found on [[https://daringfireball.net/projects/markdown/][John Gruber's website]]. @@ -114,46 +113,62 @@ Gruber's website]]. See [[https://fletcher.github.io/MultiMarkdown-6/introduction.html][its documentation]] for details on what MultiMarkdown is. The compiler can be installed through your OS's package manager: -+ MacOS: ~brew install multimarkdown~ ++ MacOS: ~$ brew install multimarkdown~ + Arch Linux: [[https://aur.archlinux.org/packages/multimarkdown/][multimarkdown]] is available on the AUR -* Features -** Markdown preview -~markdown-preview~ is bound to = p=. This will open a preview of -your compiled markdown document in your browser. +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -Alternatively, you can use ~grip-mode~ through =+grip=. +** Markdown preview +~markdown-preview~ is bound to [[kbd:][ p]]. This will open a preview of your +compiled markdown document in your browser. + +Alternatively, you can use ~grip-mode~ through [[doom-module:][+grip]]. * Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + ** Changing how markdown is compiled -When ~markdown-preview~ is invoked (= p=) it consults +When ~markdown-preview~ is invoked ([[kbd:][ p]]) it consults ~markdown-command~. Its default value (~#'+markdown-compile~) will consult -~+markdown-compile-functions~: a list of functions that take three arguments: the -start and end point in the current buffer to use as input, and an output buffer -to insert the result in. +~+markdown-compile-functions~: a list of functions that take three arguments: +the start and end point in the current buffer to use as input, and an output +buffer to insert the result in. By default, the value of ~+markdown-compile-functions~ is: - -#+BEGIN_SRC lisp +#+begin_src lisp '(+markdown-compile-marked +markdown-compile-pandoc +markdown-compile-markdown +markdown-compile-multimarkdown) -#+END_SRC +#+end_src These functions will attempt to use the marked, pandoc and markdown executables, -if available. Changing this variable will control how markdown is compiled. - -#+BEGIN_SRC elisp +if available. Changing this variable will control how markdown is compiled: +#+begin_src emacs-lisp ;; Add a new one (add-hook '+markdown-compile-functions #'my-compile-function) ;; Or remove an existing one (remove-hook '+markdown-compile-functions #'+markdown-compile-markdown) -#+END_SRC +#+end_src Otherwise, you can change ~markdown-command~ directly: - -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (setq markdown-command "markdown | smartypants") -#+END_SRC +#+end_src + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/nim/README.org b/modules/lang/nim/README.org index 67ac7c744..a5f2a2fcf 100644 --- a/modules/lang/nim/README.org +++ b/modules/lang/nim/README.org @@ -1,52 +1,74 @@ -#+TITLE: :lang Nim +# -*- mode: doom-docs-org -*- +#+title: :lang nim +#+subtitle: Python + lisp at the speed of C +#+created: May 08, 2018 +#+since: 21.12.0 (#568) -#+begin_quote -This module is a work in progress. -#+end_quote +* Description :unfold: +This module adds [[https://nim-lang.org][Nim]] support to Doom Emacs. -This module adds [[https://nim-lang.org][Nim]] support to Emacs. +- Code completion ([[doom-package:][nimsuggest]] + [[doom-package:][company]]) +- Syntax checking ([[doom-package:][nimsuggest]] + [[doom-package:][flycheck]]) +- Org babel support ([[doom-package:][ob-nim]]) -+ Code completion (nimsuggest + company) -+ Syntax checking (nimsuggest + flycheck) -+ Babel support (~ob-nim~) +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -* Table of Contents :TOC: -- [[#module-flags][Module Flags]] -- [[#prerequisites][Prerequisites]] - - [[#nim][Nim]] -- [[#configuration][Configuration]] +** Module flags +/This module has no flags./ -* Module Flags -This module provides no flags. +** Packages +- [[doom-package:][flycheck-nim]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][nim-mode]] -* Prerequisites -+ ~nim~ (for building & evaluation) -+ ~nimsuggest~ (for code completion, syntax checking & jump-to-definition functionality) +** Hacks +- [[doom-package:][nimsuggest]] was modified to strip invalid characters from its temp file paths + (which would break nimsuggest on Windows systems). +- [[doom-package:][nim-mode]] was modified to fail gracefully if =nimsuggest= (the executable) + isn't available. + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- ~nim~, for building & evaluation. +- ~nimsuggest~, for code completion, syntax checking, and jump-to-definition + functionality. ** Nim =choosenim= is an installer and version manager for the Nim programming language. You can install the latest stable release of Nim by running the following in your terminal and following the onscreen instructions: - -#+BEGIN_SRC bash +#+begin_src sh curl https://nim-lang.org/choosenim/init.sh -sSf | sh -#+END_SRC +#+end_src Alternatively, nim is usually available through your OS's package manager: +- MacOS: ~$ brew install nim~ +- Arch Linux: ~$ pacman --needed --noconfirm -S nim nimble~ +- openSUSE: ~$ zypper install nim~ -*** MacOS -#+BEGIN_SRC sh :tangle (if (doom-system-os 'macos) "yes") -brew install nim -#+END_SRC +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -*** Arch Linux -#+BEGIN_SRC sh :dir /sudo:: :tangle (if (doom-system-os 'arch) "yes") -sudo pacman --needed --noconfirm -S nim nimble -#+END_SRC +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -*** openSUSE -#+BEGIN_SRC sh :dir /sudo:: -sudo zypper install nim -#+END_SRC +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] -* Configuration +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/nix/README.org b/modules/lang/nix/README.org index 64f3d1ef3..3c94fbd9b 100644 --- a/modules/lang/nix/README.org +++ b/modules/lang/nix/README.org @@ -1,57 +1,82 @@ -#+TITLE: lang/nix -#+DATE: May 4, 2020 -#+SINCE: v2.0.7 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang nix +#+subtitle: I hereby declare "nix geht mehr!" +#+created: December 02, 2017 +#+since: 2.0.8 (#280) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#keybindings][Keybindings]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module adds support for the Nix language to Doom Emacs, along with tools +for managing [[https://nixos.org/][Nix(OS)]]. -* Description -Adds many tools for [[https://nixos.org/][Nix(OS)]] users in nice package for Doom users. - -+ Syntax highlighting -+ Completion through ~company~ / ~helm~ -+ Nix option lookup -+ Formatting (~nixfmt~) +Includes: +- Syntax highlighting +- Completion through [[doom-package:][company]] and/or [[doom-package:][helm]] +- Nix option lookup +- Formatting (~nixfmt~) ** Maintainers -This module has no dedicated maintainers. +- [[doom-user:][@hlissner]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/NixOS/nix-mode][nix-mode]] -+ [[https://github.com/jwiegley/nix-update-el][nix-update]] +** Module flags +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -* Prerequisites -+ ~nixfmt~ is required to use formatting - + If you have Nix(OS) installed it can be installed through Nix configuration ~environment.systemPackages = with pkgs; [ nixfmt ];~ (recommended) - + Or through nix-env ~nix-env -iA nixpkgs.nixfmt~ - + Or through nix-shell ~nix-shell -f https://github.com/serokell/nixfmt/archive/master.tar.gz -i~ -+ ~:editor format~ ~format-all~ also supports ~nixfmt~ so you can use that also to format Nix code, default binding is ~SPC c f~ in evil. +** Packages +- [[doom-package:][company-nixos-options]] if [[doom-module:][:completion company]] +- [[doom-package:][helm-nixos-options]] if [[doom-module:][:completion helm]] +- [[doom-package:][nix-mode]] +- [[doom-package:][nix-update]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires: +- [[https://nixos.org/guides/install-nix.html][The Nix package manager]], for a variety of its features (besides syntax + highlighting). +- =nixfmt=, for automatic formatting (requires [[doom-module:][:editor format]]). + +- *MacOS:* TODO +- *Arch Linux:* TODO +- *NixOS:* in ~pkgs.nixfmt~ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** Keybindings -| Binding | Description | -|-------------------+----------------------| -| ~ b~ | ~nix-build~ | -| ~ f~ | ~nix-update-fetch~ | -| ~ o~ | ~+nix/lookup-option~ | -| ~ p~ | ~nix-format-buffer~ | -| ~ r~ | ~nix-repl-show~ | -| ~ s~ | ~nix-repl-shell~ | -| ~ u~ | ~nix-unpack~ | +| Binding | Description | +|-----------------+----------------------| +| [[kbd:][ b]] | ~nix-build~ | +| [[kbd:][ f]] | ~nix-update-fetch~ | +| [[kbd:][ o]] | ~+nix/lookup-option~ | +| [[kbd:][ p]] | ~nix-format-buffer~ | +| [[kbd:][ r]] | ~nix-repl-show~ | +| [[kbd:][ s]] | ~nix-repl-shell~ | +| [[kbd:][ u]] | ~nix-unpack~ | -* Configuration +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * Troubleshooting -+ There aren't any known problems. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/ocaml/README.org b/modules/lang/ocaml/README.org index fa4f55586..e91aea5fe 100644 --- a/modules/lang/ocaml/README.org +++ b/modules/lang/ocaml/README.org @@ -1,93 +1,115 @@ -#+TITLE: lang/ocaml -#+DATE: June 27, 2017 -#+SINCE: v2.0.3 +# -*- mode: doom-docs-org -*- +#+title: :lang ocaml +#+subtitle: An objective camel +#+created: June 27, 2017 +#+since: 2.0.4 (#128) -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] - - [[#hacks][Hacks]] +* Description :unfold: +This module adds [[https://ocaml.org/][OCaml]] support to Doom Emacs, powered by [[doom-package:][tuareg-mode]]. -* Description -This module adds [[https://ocaml.org/][OCaml]] support to Doom Emacs, powered by [[https://github.com/ocaml/tuareg][tuareg-mode]]. +- Code completion, documentation look-up, code navigation and refactoring + ([[doom-package:][merlin]]) +- Type, documentation and function argument display on idle ([[doom-package:][merlin-eldoc]]) +- REPL ([[doom-package:][utop]]) +- Syntax-checking ([[doom-package:][merlin]] with [[doom-package:][flycheck-ocaml]]) +- Auto-indentation ([[doom-package:][ocp-indent]]) +- Code formatting ([[doom-package:][ocamlformat]]) +- Dune file format ([[doom-package:][dune]]) -+ Code completion, documentation look-up, code navigation and refactoring - ([[https://github.com/ocaml/merlin/wiki/emacs-from-scratch][merlin]]) -+ Type, documentation and function argument display on idle ([[https://github.com/Khady/merlin-eldoc][merlin-eldoc]]) -+ REPL ([[https://github.com/ocaml-community/utop][utop]]) -+ Syntax-checking (~merlin~ with [[https://github.com/flycheck/flycheck-ocaml][flycheck-ocaml]]) -+ Auto-indentation ([[https://github.com/OCamlPro/ocp-indent][ocp-indent]]) -+ Code formatting ([[https://github.com/ocaml-ppx/ocamlformat][ocamlformat]]) -+ Dune file format ([[http://dune.build/][dune]]) +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +- +lsp :: + Enable LSP support for ~tuareg-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/freebroccolo/ocaml-language-server][ocaml-language-server]]). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -** Plugins -+ [[https://github.com/ocaml/tuareg][tuareg]] -+ [[https://github.com/ocaml/merlin][merlin]] -+ [[https://github.com/Khady/merlin-eldoc][merlin-eldoc]] -+ [[https://github.com/OCamlPro/ocp-indent][ocp-indent]] -+ [[https://github.com/flycheck/flycheck-ocaml][flycheck-ocaml]]* -+ [[https://github.com/ocaml-community/utop][utop]]* -+ [[https://github.com/ocaml-ppx/ocamlformat][ocamlformat]]* -+ [[https://github.com/ocaml/dune][dune]] - -* Prerequisites -This module has no hard dependencies, but it is recommanded that you install -[[http://opam.ocaml.org/][opam]] and the following opam (optional) packages: - -#+BEGIN_SRC shell -opam install merlin utop ocp-indent dune ocamlformat -#+END_SRC - -* Features -+ The following files should have syntax highlighting support: ~.ml{i,p,y,}~, - ~.eliom{i,}~, ~jbuild~, ~dune~, ~opam~ -+ =merlin-mode= is activated whenever a =.merlin= file is found (including in a - parent directory) and =ocamlmerlin= executable is present -+ Line-based auto-indentation is provided by =ocp-indent=, if it is available. - -* Configuration -+ If =:completion company= is enabled then autocomplete is provided by =merlin= -+ When =:checkers syntax= is enabled then =flycheck-ocaml= is activated to do - on-the-fly syntax/type checking via =merlin=, otherwise this is only done when - the file is saved. -+ Spell checking is activated in comments if =:checkers spell= is active -+ A REPL is provided if =utop= is installed and =:tools eval= is active -+ If =:editor format= is enabled, the =ocamlformat= executable is available and - there is an =.ocamlformat= file present then =format-all-buffer= is bound to - =ocamlformat=, otherwise to =ocp-indent= -+ If =:editor multiple-cursors= is enabled then identifiers can be refactored - with =v R= and multiple cursors (this correctly matches identifier occurrences - according to scope, it is not purely a textual match) -+ If =:emacs imenu= is enabled then top level symbols (modules, type, functions, - etc.) can be looked up using =SPC / i= - -Run =doom sync= to install all packages and =doom doctor= to diagnose missing -tools. - -* Appendix -** Commands - | Command | Key | Description | - |------------------------------+-------------------+-----------------------------------------------------------| - | =merlin-type-enclosing= | = t= | display type under point | - | =tuareg-find-alternate-file= | = a= | switch between =.ml= and =.mli= | - | =merlin-locate= | =g d= | lookup definition | - | =merlin-occurences= | =SPC c D= | lookup references | - | =merlin-document= | =K= | lookup documentation | - | =merlin-imenu= | =SPC s i= | symbol lookup in file | - | =merlin-iedit-occurrences= | =v R= | visual refactor identifier under point (multiple cursors) | - | =utop= | =SPC o r= | open =utop= as REPL | - | =utop-eval-region= | =SPC c e= | evaluate selected region in =utop= | +** Packages +- [[doom-package:][dune]] +- [[doom-package:][ocamlformat]] if [[doom-module:][:editor format]] +- [[doom-package:][ocp-indent]] +- [[doom-package:][tuareg]] +- [[doom-package:][utop]] if [[doom-module:][:tools eval]] +- unless [[doom-module:][+lsp]] + - [[doom-package:][flycheck-ocaml]] if [[doom-module:][:checkers syntax]] + - [[doom-package:][merlin]] + - [[doom-package:][merlin-company]] + - [[doom-package:][merlin-eldoc]] ** Hacks -+ =set-ligatures!= is called with the full tuareg prettify symbol list, this - can cause columns to change as certain keywords are shortened (e.g. =fun= - becomes \lambda. -+ =tuareg-opam-update-env= is called the first time =tuareg= is loaded +- ~set-ligatures!~ is called with the full tuareg prettify symbol list, this can + cause columns to change as certain keywords are shortened (e.g. =fun= becomes + \lambda). +- ~tuareg-opam-update-env~ is called the first time [[doom-package:][tuareg]] is loaded + +** 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 following packages available through [[http://opam.ocaml.org/][opam]]: +- merlin +- utop +- ocp-indent +- dune +- ocamlformat + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- The following files should have syntax highlighting support: ~.ml{i,p,y,}~, + ~.eliom{i,}~, ~jbuild~, ~dune~, ~opam~ +- ~merlin-mode~ is activated whenever a =.merlin= file is found (including in a + parent directory) and =ocamlmerlin= executable is present +- Line-based auto-indentation is provided by =ocp-indent=, if it is available. + +| Command | Key | Description | +|------------------------------+-----------------+-----------------------------------------------------------| +| ~merlin-type-enclosing~ | [[kbd:][ t]] | display type under point | +| ~tuareg-find-alternate-file~ | [[kbd:][ a]] | switch between =.ml= and =.mli= | +| ~merlin-locate~ | [[kbd:][g d]] | lookup definition | +| ~merlin-occurences~ | [[kbd:][SPC c D]] | lookup references | +| ~merlin-document~ | [[kbd:][K]] | lookup documentation | +| ~merlin-imenu~ | [[kbd:][SPC s i]] | symbol lookup in file | +| ~merlin-iedit-occurrences~ | [[kbd:][v R]] | visual refactor identifier under point (multiple cursors) | +| ~utop~ | [[kbd:][SPC o r]] | open =utop= as REPL | +| ~utop-eval-region~ | [[kbd:][SPC c e]] | evaluate selected region in =utop= | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- If [[doom-module:][:completion company]] is enabled then autocomplete is provided by [[doom-package:][merlin]] +- When [[doom-module:][:checkers syntax]] is enabled then [[doom-package:][flycheck-ocaml]] is activated to do + on-the-fly syntax/type checking via [[doom-package:][merlin]], otherwise this is only done when + the file is saved. +- Spell checking is activated in comments if [[doom-module:][:checkers spell]] is active +- A REPL is provided if [[doom-package:][utop]] is installed and [[doom-module:][:tools eval]] is active +- If [[doom-module:][:editor format]] is enabled, the =ocamlformat= executable is available and + there is an =.ocamlformat= file present then ~format-all-buffer~ is bound to + =ocamlformat=, otherwise to =ocp-indent= +- If [[doom-module:][:editor multiple-cursors]] is enabled then identifiers can be refactored with + [[kbd:][v R]] and multiple cursors (this correctly matches identifier occurrences + according to scope, it is not purely a textual match) + +Run ~$ doom sync~ to install all packages and ~$ doom doctor~ to diagnose +missing tools. + +* 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 diff --git a/modules/lang/org/README.org b/modules/lang/org/README.org index 117839cae..30dc4083b 100644 --- a/modules/lang/org/README.org +++ b/modules/lang/org/README.org @@ -1,48 +1,28 @@ -#+TITLE: lang/org -#+DATE: February 19, 2017 -#+SINCE: 2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang org +#+subtitle: Organize your plain life in plain text +#+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]] - - [[#macos][MacOS]] - - [[#arch-linux][Arch Linux]] - - [[#nixos][NixOS]] - - [[#windows][Windows]] -- [[#features][Features]] - - [[#invoking-the-org-capture-frame-from-outside-emacs][Invoking the org-capture frame from outside Emacs]] - - [[#built-in-custom-link-types][Built-in custom link types]] -- [[#configuration][Configuration]] - - [[#changing-org-directory][Changing ~org-directory~]] - - [[#changing-org-noter-notes-search-path][Changing ~org-noter-notes-search-path~]] -- [[#troubleshooting][Troubleshooting]] - - [[#org-roam][=org-roam=]] - - [[#should-i-go-with-roam-v1-or-roam2-v2][Should I go with =+roam= (v1) or =+roam2= (v2)?]] - - [[#migrating-your-existing-files-from-v1-roam-to-v2-roam2][Migrating your existing files from v1 (=+roam=) to v2 (=+roam2=)]] - -* Description +* Description :unfold: This module adds org-mode support to Doom Emacs, along with a number of adjustments, extensions and reasonable defaults to make it more performant and intuitive out of the box: -+ A custom, centralized attachment system that stores files in one place, rather +- A custom, centralized attachment system that stores files in one place, rather than in the same directory as the input file(s) (only applies to attachments - from files in/under =org-directory=). -+ Executable code blocks with support for a variety of languages and tools + from files in/under ~org-directory~). +- Executable code blocks with support for a variety of languages and tools (depending on what :lang modules are enabled). -+ Supports an external org-capture workflow through the =bin/org-capture= shell +- Supports an external org-capture workflow through the =bin/org-capture= shell script and ~+org-capture/open-frame~. -+ A configuration for using org-mode for slide-show presentations or exporting +- A configuration for using org-mode for slide-show presentations or exporting org files to reveal.js slideshows. -+ Drag-and-drop support for images (with inline preview) and media files (drops - a file icon and a short link) (requires =+dragndrop= flag). -+ Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others +- Drag-and-drop support for images (with inline preview) and media files (drops + a file icon and a short link) (requires [[doom-module:][+dragndrop]] flag). +- Integration with pandoc, ipython, jupyter, reveal.js, beamer, and others (requires flags). -+ Export-to-clipboard functionality, for copying text into formatted html, +- Export-to-clipboard functionality, for copying text into formatted html, markdown or rich text to the clipboard (see ~+org/export-to-clipboard~ and ~+org/export-to-clipboard-as-rich-text~). @@ -56,218 +36,231 @@ executed. https://www.mfoot.com/blog/2015/11/22/literate-emacs-configuration-with-org-mode/ #+end_quote -** Module Flags -+ =+brain= Enables [[https://github.com/Kungsgeten/org-brain][org-brain]] integration. -+ =+dragndrop= Enables drag-and-drop support for images and files; inserts - inline previews for images and an icon+link for other media types. -+ =+gnuplot= Installs gnuplot & gnuplot-mode, which enables rendering images - from gnuplot src blocks or plotting tables with ~org-plot/gnuplot~ (bound to - =SPC m b p=, by default). -+ =+hugo= Enables integration with [[https://gohugo.io][hugo]] to export from Emacs well-formed - ([[https://github.com/russross/blackfriday][blackfriday]]) markdown. -+ =+ipython= (**DEPRECATED**) Enables ipython integration for babel. -+ =+journal= Enables [[https://github.com/bastibe/org-journal][org-journal]] integration. -+ =+jupyter= Enables Jupyter integration for babel. -+ =+noter= Enables org-noter integration. Keeps notes in sync with a document. - Requires [[https://github.com/politza/pdf-tools][pdf-tools]] (=:tools pdf=) or [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]] or [[https://github.com/wasamasa/nov.el][nov.el]] to be enabled. -+ =+pandoc= Enables pandoc integration into the Org exporter. -+ =+pomodoro= Enables a pomodoro timer for clocking time on tasks. -+ =+present= Enables integration with reveal.js, beamer and org-tree-slide, so - Emacs can be used for presentations. It automatically downloads [[https://github.com/hakimel/reveal.js][reveal.js]]. -+ =+pretty= Enables pretty unicode symbols for bullets and priorities, and - better syntax highlighting for latex. Keep in mind: this can be expensive. If - org becomes too slow, it'd be wise to disable this flag. -+ =+roam= Enables integration with [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be - installed on your system. Incompatible with =+roam2=. -+ =+roam2= Enables integration with [[https://github.com/org-roam/org-roam][org-roam v2]]. This requires ~sqlite3~ to be - installed on your system. Incompatible with =+roam=. +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ [[https://github.com/hniksic/emacs-htmlize][htmlize]] -+ [[https://github.com/astahlman/ob-async][ob-async]] -+ [[https://github.com/rexim/org-cliplink][org-cliplink]] -+ [[https://github.com/magit/orgit][orgit]] -+ [[https://orgmode.org/][org-plus-contrib]] -+ [[https://github.com/TobiasZawada/org-yt][org-yt]] -+ [[https://github.com/jkitchin/ox-clip][ox-clip]] -+ [[https://github.com/snosov1/toc-org][toc-org]] -+ =:lang crystal= - + [[https://github.com/brantou/ob-crystal][ob-crystal]] -+ =:lang go= - + [[https://github.com/pope/ob-go][ob-go]] -+ =:lang nim= - + [[https://github.com/Lompik/ob-nim][ob-nim]] -+ =:lang racket= - + [[https://github.com/DEADB17/ob-racket][ob-racket]] -+ =:lang rest= - + [[https://github.com/alf/ob-restclient.el][ob-restclient]] -+ =:lang rst= - + [[https://github.com/msnoigrs/ox-rst][ox-rst]] -+ =:lang rust= - + [[https://github.com/micanzhang/ob-rust][ob-rust]] -+ =:lang scala= - + [[https://github.com/zwild/ob-ammonite][ob-ammonite]] -+ =:editor evil= - + [[https://github.com/Somelauw/evil-org-mode][evil-org]] -+ =:tools pdf= - + [[https://github.com/fuxialexander/org-pdftools][org-pdftools]] -+ =+dragndrop= - + [[https://github.com/abo-abo/org-download][org-download]] -+ =+gnuplot= - + [[https://github.com/mkmcc/gnuplot-mode][gnuplot]] - + [[https://github.com/bruceravel/gnuplot-mode][gnuplot-mode]] -+ =+hugo= - + [[https://github.com/kaushalmodi/ox-hugo][ox-hugo]] -+ =+ipython= - + [[https://github.com/gregsexton/ob-ipython][ob-ipython]] -+ =+jupyter= - + [[https://github.com/dzop/emacs-jupyter][jupyter]] -+ =+pandoc= - + [[https://github.com/kawabata/ox-pandoc][ox-pandoc]] -+ =+pomodoro= - + [[https://github.com/marcinkoziej/org-pomodoro][org-pomodoro]] -+ =+present= - + [[https://github.com/anler/centered-window-mode][centered-window]] - + [[https://github.com/takaxp/org-tree-slide][org-tree-slide]] - + [[https://gitlab.com/oer/org-re-reveal][org-re-reveal]] -+ =+pretty= - + [[https://github.com/integral-dw/org-superstar-mode][org-superstar]] - + [[https://github.com/harrybournis/org-fancy-priorities][org-fancy-priorities]] -+ =+roam= - + [[https://github.com/org-roam/org-roam-v1][org-roam]] (v1) -+ =+roam2= - - [[https://github.com/org-roam/org-roam][org-roam]] (v2) -+ =+noter= - + [[https://github.com/weirdNox/org-noter][org-noter]] +[[doom-contrib-maintainer:][Become a maintainer?]] +** Module flags +- +brain :: + Enable [[https://github.com/Kungsgeten/org-brain][org-brain]] integration. +- +dragndrop :: + Enable drag-and-drop support for images and files; inserts inline previews + for images and an icon+link for other media types. +- +gnuplot :: + Install gnuplot & gnuplot-mode, which enables rendering images from gnuplot + src blocks or plotting tables with ~org-plot/gnuplot~ (bound to =SPC m b p=, + by default). +- +hugo :: + Enable integration with [[https://gohugo.io][hugo]] to export from Emacs well-formed ([[https://github.com/russross/blackfriday][blackfriday]]) + markdown. +- +ipython :: + (**DEPRECATED**) Enable ipython integration for babel. +- +journal :: + Enable [[doom-package:][org-journal]] integration. +- +jupyter :: + Enable Jupyter integration for babel. +- +noter :: + Enable [[doom-package:][org-noter]] integration. Keeps notes in sync with a document. Requires + [[doom-module:][:tools pdf]], [[https://www.gnu.org/software/emacs/manual/html_node/emacs/Document-View.html][DocView]], or [[https://github.com/wasamasa/nov.el][nov.el]] to be enabled. +- +pandoc :: + Enable pandoc integration into the Org exporter. +- +pomodoro :: + Enable a pomodoro timer for clocking time on tasks. +- +present :: + Enable integration with reveal.js, beamer and org-tree-slide, so Emacs can be + used for presentations. It automatically downloads [[https://github.com/hakimel/reveal.js][reveal.js]]. +- +pretty :: + Enable pretty unicode symbols for bullets+priorities and better syntax + highlighting for latex. Keep in mind: this can be expensive. If org becomes + too slow, it'd be wise to disable this flag. +- +roam :: + Enable integration with [[https://github.com/org-roam/org-roam-v1][org-roam v1]]. This requires ~sqlite3~ to be installed + on your system. /Incompatible with [[doom-module:][+roam2]]./ +- +roam2 :: + Enable integration with [[https://github.com/org-roam/org-roam][org-roam v2]]. This requires ~sqlite3~ to be installed + on your system. /Incompatible with [[doom-module:][+roam]]./ + +** Packages +- [[doom-package:][evil-org]] if [[doom-package:][:editor evil]] +- [[doom-package:][htmlize]] +- [[doom-package:][jupyter]] if [[doom-package:][+jupyter]] +- [[doom-package:][ob-ammonite]] if [[doom-package:][:lang scala]] +- [[doom-package:][ob-async]] +- [[doom-package:][ob-crystal]] if [[doom-package:][:lang crystal]] +- [[doom-package:][ob-go]] if [[doom-package:][:lang go]] +- [[doom-package:][ob-ipython]] if [[doom-package:][+ipython]] +- [[doom-package:][ob-nim]] if [[doom-package:][:lang nim]] +- [[doom-package:][ob-racket]] if [[doom-package:][:lang racket]] +- [[doom-package:][ob-restclient]] if [[doom-package:][:lang rest]] +- [[doom-package:][ob-rust]] if [[doom-package:][:lang rust]] +- [[doom-package:][org-cliplink]] +- [[doom-package:][org-download]] if [[doom-package:][+dragndrop]] +- [[doom-package:][orgit]] +- [[doom-package:][org-noter]] if [[doom-package:][+noter]] +- [[doom-package:][org-pdftools]] if [[doom-package:][:tools pdf]] +- [[doom-package:][org-plus-contrib]] +- [[doom-package:][org-pomodoro]] if [[doom-package:][+pomodoro]] +- [[doom-package:][org-roam]] (v1) if [[doom-package:][+roam]] +- [[doom-package:][org-roam]] (v2) if [[doom-package:][+roam2]] +- [[doom-package:][org-yt]] +- [[doom-package:][ox-clip]] +- [[doom-package:][ox-hugo]] if [[doom-package:][+hugo]] +- [[doom-package:][ox-pandoc]] if [[doom-package:][+pandoc]] +- [[doom-package:][ox-rst]] if [[doom-package:][:lang rst]] +- [[doom-package:][toc-org]] +- if [[doom-package:][+gnuplot]] + - [[doom-package:][gnuplot]] + - [[doom-package:][gnuplot-mode]] +- if [[doom-package:][+present]] + - [[doom-package:][centered-window]] + - [[doom-package:][org-tree-slide]] + - [[doom-package:][org-re-reveal]] +- if [[doom-package:][+pretty]] + - [[doom-package:][org-superstar]] + - [[doom-package:][org-fancy-priorities]] ** Hacks -+ Adds support for a ~:sync~ parameter for org src blocks. This overrides +- Adds support for a ~:sync~ parameter for org src blocks. This overrides ~:async~. -+ Gracefully degrades ~:async~ babel blocks to ~:sync~ when =ob-async= would - cause errors or issues (such as with a ~:session~ parameter, which =ob-async= - does not support, or when exporting org documents). -+ The window is recentered when following links. -+ The breadcrumbs displayed in eldoc when hovering over an org headline has been +- Gracefully degrades ~:async~ babel blocks to ~:sync~ when [[doom-package:][ob-async]] would cause + errors or issues (such as with a ~:session~ parameter, which [[doom-package:][ob-async]] does not + support, or when exporting org documents). +- The window is recentered when following links. +- The breadcrumbs displayed in eldoc when hovering over an org headline has been reworked to strip out link syntax and normalize font-size disparities. -+ If =:ui workspaces= is enabled, persp-mode won't register org agenda buffers that - are temporarily opened in the background. -+ Temporary org agenda files aren't added to recentf. -+ =file:= links are highlighted with the ~error~ face if they are broken. -+ TAB was changed to toggle only the visibility state of the current subtree, +- If [[doom-module:][:ui workspaces]] is enabled, persp-mode won't register org agenda buffers + that are temporarily opened in the background. +- Temporary org agenda files aren't added to recentf. +- =file:= links are highlighted with the ~error~ face if they are broken. +- TAB was changed to toggle only the visibility state of the current subtree, rather than cycle through it recursively. This can be reversed with: - #+BEGIN_SRC emacs-lisp + #+begin_src emacs-lisp (after! evil-org (remove-hook 'org-tab-first-hook #'+org-cycle-only-current-subtree-h)) - #+END_SRC -+ (Evil users) Nearby tables are formatted when exiting insert or replace mode + #+end_src +- (Evil users) Nearby tables are formatted when exiting insert or replace mode (see ~+org-enable-auto-reformat-tables-h~). -+ Statistics cookies are updated when saving the buffer of exiting insert mode +- Statistics cookies are updated when saving the buffer of exiting insert mode (see ~+org-enable-auto-update-cookies-h~). -+ Org-protocol has been lazy loaded (see ~+org-init-protocol-lazy-loader-h~); +- Org-protocol has been lazy loaded (see ~+org-init-protocol-lazy-loader-h~); loaded when the server receives a request for an org-protocol:// url. -+ Babel and babel plugins are now lazy loaded (see +- Babel and babel plugins are now lazy loaded (see ~+org-init-babel-lazy-loader-h~); loaded when a src block is executed. No need to use ~org-babel-do-load-languages~ in your config, just install your babel packages to extend language support (and ensure its ~org-babel-execute:*~ function is autoloaded). -+ If a variable is used as a file path in ~org-capture-template~, it will be +- If a variable is used as a file path in ~org-capture-template~, it will be resolved relative to ~org-directory~, instead of ~default-directory~ (see ~+org-capture-expand-variable-file-a~). -* Prerequisites -Org has a few soft dependencies that you will need to make use of Org's more -esoteric features: +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -+ For inline LaTeX previews, ~latex~ and ~dvipng~ is needed. -+ To render GNUPlot images (with =+gnuplot= flag) the ~gnuplot~ program is - needed. -+ To execute babel code blocks, you need whatever dependencies those languages - need. It is recommended you enable the associated =:lang= module and ensure - its dependencies are met, e.g. install the =ruby= executable for ruby support. - To use ~jupyter kernels~ you need the =+jupyter= flag, the associated kernel as +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module has no hard requirements, but these soft requirements are needed to +use Org's more esoteric features: +- For inline LaTeX previews, ~latex~ and ~dvipng~ is needed. +- To render GNUPlot images (with [[doom-module:][+gnuplot]] flag) the ~gnuplot~ program is needed. +- To execute babel code blocks, you need whatever dependencies those languages + need. It is recommended you enable the associated [[doom-module:][:lang]] module and ensure its + dependencies are met, e.g. install the =ruby= executable for ruby support. To + use ~jupyter kernels~ you need the [[doom-module:][+jupyter]] flag, the associated kernel as well as the ~jupyter~ program. -+ =org-roam= (with =+roam= or =+roam2= flag) requires =sqlite3= to be installed. +- [[doom-package:][org-roam]] (with [[doom-module:][+roam]] or [[doom-module:][+roam2]] flag) requires =sqlite3= to be installed. ** MacOS -#+BEGIN_SRC sh +#+begin_src sh brew install --cask mactex brew install gnuplot -#+END_SRC +#+end_src ** Arch Linux -#+BEGIN_SRC sh -pacman -S texlive-core texlive-bin texlive-science +#+begin_src sh +pacman -S texlive-core texlive-bin texlive-science texlive-latexextra pacman -S gnuplot pacman -S jupyter # required by +jupyter -#+END_SRC +#+end_src ** NixOS -#+BEGIN_SRC nix +#+begin_src nix environment.systemPackages = with pkgs; [ # any less than medium isn't guaranteed to work texlive.combined.scheme-medium # required by +jupyter (python38.withPackages(ps: with ps; [jupyter])) ]; -#+END_SRC +#+end_src ** TODO Windows -* Features +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + ** Invoking the org-capture frame from outside Emacs The simplest way to use the org-capture frame is through the ~bin/org-capture~ script. I'd recommend binding a shortcut key to it. If Emacs isn't running, it will spawn a temporary daemon for you. Alternatively, you can call ~+org-capture/open-frame~ directly, e.g. - -#+BEGIN_SRC sh -emacsclient --eval '(+org-capture/open-frame INTIAL-INPUT KEY)' -#+END_SRC +#+begin_src sh +emacsclient --eval '(+org-capture/open-frame INITIAL-INPUT KEY)' +#+end_src ** Built-in custom link types This module defines a number of custom link types in ~+org-init-custom-links-h~. They are (with examples): -+ ~doom-docs:news/2.1.0~ (=~/.emacs.d/docs/%s=) -+ ~doom-modules:editor/evil/README.org~ (=~/.emacs.d/modules/%s=) -+ ~doom-repo:issues~ (=https://github.com/hlissner/doom-emacs/%s=) -+ ~doom:core/core.el~ (=~/.emacs.d/%s=) -+ ~duckduckgo:search terms~ -+ ~gimages:search terms~ (Google Images) -+ ~github:hlissner/doom-emacs~ -+ ~gmap:Toronto, Ontario~ (Google Maps) -+ ~google:search terms~ -+ ~org:todo.org~ (={org-directory}/%s=) -+ ~wolfram:sin(x^3)~ -+ ~wikipedia:Emacs~ -+ ~youtube:P196hEuA_Xc~ (link only) -+ ~yt:P196hEuA_Xc~ (like =youtube=, but includes an inline preview of the video) +- ~doom-docs:index.org~ -> =~/.emacs.d/docs/%s= +- ~doom-modules:editor/evil/README.org~ -> =~/.emacs.d/modules/%s= +- ~doom-repo:issues~ -> =https://github.com/hlissner/doom-emacs/%s= +- ~doom:core/core.el~ -> =~/.emacs.d/%s= +- ~duckduckgo:search terms~ +- ~gimages:search terms~ (Google Images) +- ~github:hlissner/doom-emacs~ +- ~gmap:Toronto, Ontario~ (Google Maps) +- ~google:search terms~ +- ~org:todo.org~ -> ={org-directory}/%s= +- ~wolfram:sin(x^3)~ +- ~wikipedia:Emacs~ +- ~youtube:P196hEuA_Xc~ (link only) +- ~yt:P196hEuA_Xc~ (like =youtube=, but includes an inline preview of the video) + +** evil-mode keybindings +For =evil-mode= users, an overview of org-mode keybindings is provided [[https://github.com/Somelauw/evil-org-mode/blob/master/README.org#keybindings][here]]. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Changing ~org-directory~ -To modify ~org-directory~ it must be set /before/ =org= has loaded: - -#+BEGIN_SRC emacs-lisp -;; ~/.doom.d/config.el +~org-directory~ must be set /before/ [[doom-package:][org]] has loaded: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq org-directory "~/new/org/location/") -#+END_SRC -** Changing ~org-noter-notes-search-path~ -To modify ~org-noter-notes-search-path~ set: +#+end_src -#+BEGIN_SRC emacs-lisp -;; ~/.doom.d/config.el +** Changing ~org-noter-notes-search-path~ +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq org-noter-notes-search-path '("~/notes/path/")) -#+END_SRC +#+end_src * Troubleshooting +[[doom-report:][Report an issue?]] + ** =org-roam= *** Should I go with =+roam= (v1) or =+roam2= (v2)? -Long story short: if you're new to =org-roam= and haven't used it, then you -should go with =+roam2=; if you already have an ~org-roam-directory~ with the v1 -files in it, then you can keep use =+roam= for a time being. +Long story short: if you're new to [[doom-package:][org-roam]] and haven't used it, then you should +go with [[doom-module:][+roam2]]; if you already have an ~org-roam-directory~ with the v1 files in +it, then you can keep use [[doom-module:][+roam]] for a time being. V1 isn't actively maintained anymore and is now basically EOL. This means that the feature disparity between the both will continue to grow, while its existing @@ -291,14 +284,22 @@ appear during the migration process. Because of that, *don't forget to backup* your ~org-roam-directory~ before attempting to migrate. In order to migrate from v1 to v2 using Doom follow the next steps: -1. Enable =+roam2= flag (and disable =+roam= if it was previously enabled) in - your =init.el=. +1. Enable [[doom-module:][+roam2]] flag (and disable [[doom-module:][+roam]] if it was previously enabled) in your + =init.el=. 2. Ensure your ~org-roam-directory~ points to a directory with your v1 files. -3. Run =doom sync -u= in your shell. +3. Run ~$ doom sync -u~ in your shell. 4. Restart Emacs (if it was previously opened) and run ~org-roam-migrate-wizard~ - command (=M-x org-roam-migrate-wizard RET=). The wizard will automatically + command (~M-x org-roam-migrate-wizard RET~). The wizard will automatically attempt to backup your previous ~org-roam-directory~ to =org-roam.bak=, but just in case backup it yourself too. 4. After the wizard is done you should be good to go. Verify the integrity of your data and whether it did everything as expected. In case of failure [[https://github.com/org-roam/org-roam/issues][report]] your issue. + +* 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 diff --git a/modules/lang/org/autoload/org-link.el b/modules/lang/org/autoload/org-link.el index 50675947d..ebf47b6a3 100644 --- a/modules/lang/org/autoload/org-link.el +++ b/modules/lang/org/autoload/org-link.el @@ -9,19 +9,6 @@ (let ((file (funcall (or fn #'read-file-name) (format "%s: " (capitalize key)) dir))) (format "%s:%s" key (file-relative-name file dir)))) -;;;###autoload -(defun +org-read-link-description-at-point (&optional default context) - "TODO" - (if (and (stringp default) (not (string-empty-p default))) - (string-trim default) - (if-let* ((context (or context (org-element-context))) - (context (org-element-lineage context '(link) t)) - (beg (org-element-property :contents-begin context)) - (end (org-element-property :contents-end context))) - (unless (= beg end) - (replace-regexp-in-string - "[ \n]+" " " (string-trim (buffer-substring-no-properties beg end))))))) - ;;;###autoload (defun +org-define-basic-link (key dir-var &rest plist) "Define a link with some basic completion & fontification. @@ -166,83 +153,3 @@ exist, and `org-link' otherwise." (user-error "Not in org-mode")) (or (+org-play-gif-at-point-h) (user-error "No gif at point"))) - - -;; -;;; Org-link parameters - -;;; doom-module: -(defun +org-link--doom-module--read-link (link) - (cl-destructuring-bind (category &optional module flag) - (let ((desc (+org-read-link-description-at-point link))) - (if (string-prefix-p "+" (string-trim-left desc)) - (list nil nil (intern desc)) - (mapcar #'intern (split-string desc " " nil)))) - (list :category category - :module module - :flag flag))) - -;;;###autoload -(defun +org-link--doom-module-follow-fn (link) - (cl-destructuring-bind (&key category module flag) - (+org-link--doom-module--read-link link) - (when category - (let ((doom-modules-dirs (list doom-modules-dir))) - (if-let* ((path (doom-module-locate-path category module)) - (path (or (car (doom-glob path "README.org")) - path))) - (find-file path) - (user-error "Can't find Doom module '%s'" link)))) - (when flag - (goto-char (point-min)) - (and (re-search-forward "^\\*+ \\(?:TODO \\)?Module Flags") - (re-search-forward (format "^\\s-*- %s :: " - (regexp-quote (symbol-name flag))) - (save-excursion (org-get-next-sibling) - (point))) - (recenter))))) - -;;;###autoload -(defun +org-link--doom-module-face-fn (link) - (cl-destructuring-bind (&key category module flag) - (+org-link--doom-module--read-link link) - (if (doom-module-locate-path category module) - `(:inherit org-priority - :weight bold) - 'error))) - - -;;; doom-package: -;;;###autoload -(defun +org-link--doom-package-follow-fn (link) - "TODO" - (doom/describe-package - (intern-soft - (+org-read-link-description-at-point link)))) - - -;;; kbd: - -(defun +org--describe-kbd (keystr) - (dolist (key `(("" . ,doom-leader-key) - ("" . ,doom-localleader-key) - ("" . ,(if (bound-and-true-p evil-mode) - (concat doom-leader-key " u") - "C-u")) - ("" . ,(if (bound-and-true-p evil-mode) - (concat doom-leader-key " h") - "C-h")) - ("\\ m c c~ | ~composer~ | -| ~ m c i~ | ~composer-install~ | -| ~ m c r~ | ~composer-require~ | -| ~ m c u~ | ~composer-update~ | -| ~ m c d~ | ~composer-dump-autoload~ | -| ~ m c s~ | ~composer-run-scripts~ | -| ~ m c v~ | ~composer-run-vendor-bin-command~ | -| ~ m c o~ | ~composer-find-json-file~ | -| ~ m c l~ | ~composer-view-lock-file~ | +| Binding | Function | +|---------------------+-----------------------------------| +| [[kbd:][ m c c]] | ~composer~ | +| [[kbd:][ m c i]] | ~composer-install~ | +| [[kbd:][ m c r]] | ~composer-require~ | +| [[kbd:][ m c u]] | ~composer-update~ | +| [[kbd:][ m c d]] | ~composer-dump-autoload~ | +| [[kbd:][ m c s]] | ~composer-run-scripts~ | +| [[kbd:][ m c v]] | ~composer-run-vendor-bin-command~ | +| [[kbd:][ m c o]] | ~composer-find-json-file~ | +| [[kbd:][ m c l]] | ~composer-view-lock-file~ | -These are all invokable via =M-x= too. +These are all invokable via [[kbd:][M-x]] too. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Docker Compose A lot of projects rely on running inside docker compose (ie Laravel), and as such a minor mode has been configured to attempt to run tests inside the =php-fpm= @@ -210,11 +207,12 @@ If you wish to specify a different container, modify the #+end_src * Troubleshooting +[[doom-report:][Report an issue?]] + ** "I'm missing functionality on lsp-mode" Unfortunately, [[https://intelephense.com/][intelephense]] currently operates under a "freemium" model, and as such requires a license for extended features. Once purchased, this can be (insecurely) added directly to your config: - #+begin_src emacs-lisp (setq lsp-intelephense-licence-key "") #+end_src @@ -223,14 +221,12 @@ A more recommended approach would be to utilise Emacs' own ~auth-sources~ for storing authentication info, which can also be encrypted. Create a file in your home directory (which can optionally be encrypted, verify -your ~auth-sources~ has the correct values) called ~~/.authinfo~ - +your ~auth-sources~ has the correct values) called ~~/.authinfo~: #+begin_src machine * login intelephense password #+end_src -And add the following to your config - +And add the following to your config: #+begin_src emacs-lisp (defun my-fetch-password (&rest params) (require 'auth-source) @@ -242,5 +238,13 @@ And add the following to your config secret)) (error "Password not found for %S" params)))) -(setq lsp-intelephense-license-key (my-fetch-password :user intelephense)) +(setq lsp-intelephense-licence-key (my-fetch-password :user intelephense)) #+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 diff --git a/modules/lang/plantuml/README.org b/modules/lang/plantuml/README.org new file mode 100644 index 000000000..9c9eb8bc7 --- /dev/null +++ b/modules/lang/plantuml/README.org @@ -0,0 +1,52 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang plantuml +#+subtitle: Diagrams to confuse people more +#+created: July 08, 2017 +#+since: 2.0.4 + +* Description :unfold: +This module adds plantuml support to Emacs; allowing you to generate diagrams +from plain text. + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][plantuml-mode]] +- [[doom-package:][flycheck-plantuml]] if [[doom-module:][:checkers syntax]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires =plantuml= to build diagrams with. + +* 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 diff --git a/modules/lang/purescript/README.org b/modules/lang/purescript/README.org new file mode 100644 index 000000000..7aca11789 --- /dev/null +++ b/modules/lang/purescript/README.org @@ -0,0 +1,56 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang purescript +#+subtitle: Javascript, but functional +#+created: May 21, 2017 +#+since: 2.0.3 (#75) + +* Description :unfold: +This module adds [[https://www.purescript.org/][Purescript]] support to Doom Emacs. + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~purescript-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/nwolverson/purescript-language-server][purescript-language-server]]). + +** Packages +- [[doom-package:][psci]] +- [[doom-package:][psc-ide]] +- [[doom-package:][purescript-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./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote +πŸ”¨ /This module's prerequisites are not documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/python/README.org b/modules/lang/python/README.org index 41b2aafb1..c9942179e 100644 --- a/modules/lang/python/README.org +++ b/modules/lang/python/README.org @@ -1,130 +1,156 @@ -#+TITLE: lang/python -#+DATE: Oct, 2019 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang python +#+subtitle: Beautiful is better than ugly +#+created: June 15, 2015 +#+since: 0.7 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#language-server-protocol-support][Language Server Protocol Support]] -- [[#features][Features]] - - [[#keybindings][Keybindings]] -- [[#configuration][Configuration]] +* Description :unfold: +This module adds [[https://www.python.org/][Python]] support to Doom Emacs. -* Description -Adds Python support to Doom Emacs. +- Syntax checking ([[doom-package:][flycheck]]) +- Snippets +- Run tests ([[doom-package:][nose]], [[doom-package:][pytest]]) +- Auto-format (with ~black~, requires [[doom-module:][:editor format]]) +- LSP integration (=mspyls=, =pyls=, or =pyright=) -+ Syntax checking (~flycheck~) -+ Snippets -+ Run tests (~nose~, ~pytest~) -+ Auto-format (~black~), requires ~:editor format~ -+ LSP integration (mspyls, pyls, or pyright) +** Maintainers +- [[doom-user:][@hlissner]] -** Module Flags -+ ~+lsp~ Language Server Protocol support -+ ~+pyright~ Use the pyright LSP server instead of mspyls or pyls (requires - ~+lsp~). -+ ~+pyenv~ Python virtual environment support via [[https://github.com/pyenv/pyenv][pyenv]] -+ ~+conda~ Python virtual environment support via [[https://conda.io/en/latest/][Conda]] -+ ~+poetry~ Python packaging, dependency management, and virtual environment - support via [[https://python-poetry.org/][Poetry]] -+ ~+cython~ Cython files support via [[https://github.com/cython/cython/blob/master/Tools/cython-mode.el][cython-mode]] +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/pythonic-emacs/anaconda-mode][anaconda-mode]]* -+ [[https://github.com/Wilfred/pyimport][pyimport]]* -+ [[https://github.com/paetzke/py-isort.el][py-isort]]* -+ [[https://github.com/emacsattic/nose/][nose]]* -+ [[https://github.com/wbolster/emacs-python-pytest][python-pytest]]* -+ [[https://github.com/Wilfred/pip-requirements.el][pip-requirements]]* -+ [[https://github.com/pwalsh/pipenv.el][pipenv]]* -+ if ~+conda~ - + [[https://github.com/necaris/conda.el][conda]]* -+ if ~+pyenv~ - + [[https://github.com/pythonic-emacs/pyenv-mode][pyenv]]* -+ if ~+poetry~ - + [[https://github.com/galaunay/poetry.el][poetry]]* -+ if ~+lsp~ and ~:tools lsp~ - + [[https://github.com/emacs-lsp/lsp-mode][lsp]] - + if ~+pyright~ - + [[https://github.com/emacs-lsp/lsp-pyright][lsp-pyright]] - + else - + [[https://github.com/emacs-lsp/lsp-python-ms][lsp-python-ms]] -+ if ~+cython~ - + [[https://github.com/cython/cython/blob/master/Tools/cython-mode.el][cython-mode]] - + if ~:checkers syntax~: [[https://github.com/lbolla/emacs-flycheck-cython/tree/master][flycheck-cython]] +** Module flags +- +conda :: + Enable python virtual environment support via [[https://conda.io/en/latest/][Conda]]. +- +cython :: + Enable support for Cython files support. +- +lsp :: + Enable LSP support for ~python-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports mspyls, pyls, and pyright). +- +poetry :: + Enable Python packaging, dependency management, and virtual environment + support via [[https://python-poetry.org/][Poetry]]. +- +pyenv :: + Enable Python virtual environment support via [[https://github.com/pyenv/pyenv][pyenv]] +- +pyright :: + Use the pyright LSP server instead of mspyls or pyls (requires [[doom-module:][+lsp]]). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -* Prerequisites -This module has no hard prerequisites, but a few soft ones: +** Packages +- [[doom-package:][anaconda-mode]] +- [[doom-package:][conda]] +- [[doom-package:][nose]] +- [[doom-package:][pipenv]] +- [[doom-package:][pip-requirements]] +- [[doom-package:][poetry]] if [[doom-module:][+poetry]] +- [[doom-package:][pyenv]] +- [[doom-package:][pyimport]] +- [[doom-package:][py-isort]] +- [[doom-package:][python-pytest]] +- if [[doom-module:][+cython]] + - [[doom-package:][cython-mode]] + - [[doom-package:][flycheck-cython]] if [[doom-module:][:checkers syntax]] +- if [[doom-module:][+lsp]] + - if [[doom-module:][+pyright]] + - [[doom-package:][lsp-pyright]] + - else + - [[doom-package:][lsp-python-ms]] -+ For this module's supported test runners: - + ~pip install pytest~ - + ~pip install nose~ -+ The ~:editor format~ module uses [[https://github.com/psf/black][Black]] for python files :: ~pip install black~ -+ ~pyimport~ requires Python's module ~pyflakes~ :: ~pip install pyflakes~ -+ ~py-isort~ requires [[https://github.com/timothycrosley/isort][isort]] to be installed :: ~pip install isort~ -+ Python virtual environments install instructions at: - + [[https://github.com/pyenv/pyenv][pyenv]] - + [[https://conda.io/en/latest/][Conda]] - + [[https://python-poetry.org/][Poetry]] - + [[https://pipenv.readthedocs.io/en/latest/][pipenv]] -+ ~cython~ requires [[https://cython.org/][Cython]] +** Hacks +- [[doom-package:][anaconda-mode]] is configured to activate when [[doom-package:][lsp-mode]] (or [[doom-package:][eglot]]) don't -- or + fail to. + +** 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 hard requirements, but softly depends on: +- For this module's supported test runners: + - ~$ pip install pytest~ + - ~$ pip install nose~ +- The [[doom-module:][:editor format]] module uses Black for python files: ~$ pip install black~ +- [[doom-package:][pyimport]] requires Python's module ~pyflakes~: ~$ pip install pyflakes~ +- [[doom-package:][py-isort]] requires [[https://github.com/timothycrosley/isort][isort]] to be installed: ~pip install isort~ +- Python virtual environments install instructions at: + - [[https://github.com/pyenv/pyenv][pyenv]] + - [[https://conda.io/en/latest/][Conda]] + - [[https://python-poetry.org/][Poetry]] + - [[https://pipenv.readthedocs.io/en/latest/][pipenv]] +- ~cython~ requires [[https://cython.org/][Cython]] ** Language Server Protocol Support -For LSP support the =:tools lsp= module must be enabled, along with this -module's =+lsp= flag. By default, it supports =mspyls= and =pyls=, in that -order. With the =+pyright= flag, it will try Pyright first. +For LSP support the [[doom-module:][:tools lsp]] module must be enabled, along with this module's +[[doom-module:][+lsp]] flag. By default, it supports [[doom-package:][mspyls]] and [[doom-package:][pyls]], in that order. With the +[[doom-module:][+pyright]] flag, it will try Pyright first. Each of these servers must be installed on your system via your OS package manager or manually: +- [[https://pypi.org/project/python-language-server/][*pyls*]] can be installed with ~$ pip install python-language-server[all]~. +- *mspyls* can be installed by typing ~M-x lsp-install-server RET mspyls~. +- *pyright* can be installed with ~$ pip install pyright~ or ~$ npm i -g + pyright~. -+ [[https://pypi.org/project/python-language-server/][*pyls*]] can be installed with ~pip install python-language-server[all]~. -+ *mspyls* can be installed by typing =M-x lsp-install-server RET mspyls=. -+ *pyright* can be installed with ~pip install pyright~ or ~npm i -g pyright~. +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features -This module supports LSP. It requires installation of [[https://pypi.org/project/python-language-server/][Python Language -Server]], [[https://github.com/Microsoft/python-language-server][Microsoft Language Server]], or [[https://github.com/microsoft/pyright][pyright]], see [[Language Server Protocol Support][LSP Support]]. +This module supports LSP. It requires installation of [[https://pypi.org/project/python-language-server/][Python Language Server]], +[[https://github.com/Microsoft/python-language-server][Microsoft Language Server]], or [[https://github.com/microsoft/pyright][pyright]], see [[Language Server Protocol Support][LSP Support]]. -To enable support for auto-formatting with black enable ~:editor format~ in -~init.el~ file. +To enable support for auto-formatting with black enable [[doom-module:][:editor format]]. ** Keybindings +| Binding | Description | +|-------------------+----------------------------------| +| [[kbd:][ c c]] | ~Compile Cython buffer~ | +| [[kbd:][ i i]] | ~Insert mising imports~ | +| [[kbd:][ i r]] | ~Remove unused imports~ | +| [[kbd:][ i s]] | ~Sort imports~ | +| [[kbd:][ i o]] | ~Optimize imports~ | +| [[kbd:][ t r]] | ~nosetests-again~ | +| [[kbd:][ t a]] | ~nosetests-all~ | +| [[kbd:][ t s]] | ~nosetests-one~ | +| [[kbd:][ t v]] | ~nosetests-module~ | +| [[kbd:][ t A]] | ~nosetests-pdb-all~ | +| [[kbd:][ t O]] | ~nosetests-pdb-one~ | +| [[kbd:][ t V]] | ~nosetests-pdb-module~ | +| [[kbd:][ t f]] | ~python-pytest-file~ | +| [[kbd:][ t k]] | ~python-pytest-file-dwim~ | +| [[kbd:][ t t]] | ~python-pytest-function~ | +| [[kbd:][ t m]] | ~python-pytest-function-dwim~ | +| [[kbd:][ t r]] | ~python-pytest-repeat~ | +| [[kbd:][ t p]] | ~python-pytest-popup~ | +| [[kbd:][ g d]] | ~anaconda-mode-find-definitions~ | +| [[kbd:][ g h]] | ~anaconda-mode-show-doc~ | +| [[kbd:][ g a]] | ~anaconda-mode-find-assignments~ | +| [[kbd:][ g f]] | ~anaconda-mode-find-file~ | +| [[kbd:][ g u]] | ~anaconda-mode-find-references~ | -| Binding | Description | -|---------------------+----------------------------------| -| ~ c c~ | ~Compile Cython buffer~ | -| ~ i i~ | ~Insert mising imports~ | -| ~ i r~ | ~Remove unused imports~ | -| ~ i s~ | ~Sort imports~ | -| ~ i o~ | ~Optimize imports~ | -| ~ t r~ | ~nosetests-again~ | -| ~ t a~ | ~nosetests-all~ | -| ~ t s~ | ~nosetests-one~ | -| ~ t v~ | ~nosetests-module~ | -| ~ t A~ | ~nosetests-pdb-all~ | -| ~ t O~ | ~nosetests-pdb-one~ | -| ~ t V~ | ~nosetests-pdb-module~ | -| ~ t f~ | ~python-pytest-file~ | -| ~ t k~ | ~python-pytest-file-dwim~ | -| ~ t t~ | ~python-pytest-function~ | -| ~ t m~ | ~python-pytest-function-dwim~ | -| ~ t r~ | ~python-pytest-repeat~ | -| ~ t p~ | ~python-pytest-popup~ | -| ~ g d~ | ~anaconda-mode-find-definitions~ | -| ~ g h~ | ~anaconda-mode-show-doc~ | -| ~ g a~ | ~anaconda-mode-find-assignments~ | -| ~ g f~ | ~anaconda-mode-find-file~ | -| ~ g u~ | ~anaconda-mode-find-references~ | +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration This module has the following variables to set extra arguments to [[https://ipython.org/][ipython]] and [[https://jupyter.org/][jupyter]] shells: - -#+BEGIN_SRC elisp -;; ~/.doom.d/config.el +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq +python-ipython-repl-args '("-i" "--simple-prompt" "--no-color-info")) (setq +python-jupyter-repl-args '("--simple-prompt")) -#+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 diff --git a/modules/lang/qt/README.org b/modules/lang/qt/README.org index 36c244f9e..bd42f38a2 100644 --- a/modules/lang/qt/README.org +++ b/modules/lang/qt/README.org @@ -1,31 +1,54 @@ -#+TITLE: lang/qt -#+DATE: May 22, 2021 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang qt +#+subtitle: The cutest GUI framework ever +#+created: June 02, 2018 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - -* Description -# A summary of what this module does. +* Description :unfold: This module provides language functionality for [[https://qt.io][Qt]] specific files. -+ Syntax highlighting for [[https:://en.wikipedia.org/wiki/QML][qml]] files -+ Syntax highlighting for .pro and .pri files used by [[https://doc.qt.io/qt-5/qmake-project-files.html][qmake]] +- Syntax highlighting for [[https:://en.wikipedia.org/wiki/QML][qml]] files +- Syntax highlighting for =.pro= and =.pri= files used by [[https://doc.qt.io/qt-5/qmake-project-files.html][qmake]] ** Maintainers -This module has no dedicated maintainers. +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/coldnew/qml-mode/tree/master][qml-mode]] -+ [[https://github.com/EricCrosson/qt-pro-mode][qt-pro-mode]] +** Packages +- [[doom-package:][qml-mode]] +- [[doom-package:][qt-pro-mode]] -* Prerequisites -This module has no prerequisites. +** 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 diff --git a/modules/lang/racket/README.org b/modules/lang/racket/README.org index 31df6f6dd..db2b64303 100644 --- a/modules/lang/racket/README.org +++ b/modules/lang/racket/README.org @@ -1,70 +1,89 @@ -#+TITLE: lang/racket -#+DATE: July 29, 2018 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang racket +#+subtitle: The DSL for DSLs +#+created: July 29, 2018 +#+since: 2.0.9 (#772) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#arch-linux][Arch Linux]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#racket-smart-open-bracket-mode][racket-smart-open-bracket-mode]] - - [[#unicode-input][Unicode Input]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This module provides integration for [[https://github.com/greghendershott/racket-mode][racket-mode]]. +* Description :unfold: +This module adds support for the [[https://www.racket-lang.org/][Racket programming language]] to Doom Emacs. ** Maintainers -This module has no dedicated maintainers. +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+lsp= Enables LSP support. Requires jeapostrophe/racket-langserver. -+ =+xp= Enables the explore mode, which "analyzes expanded code to explain and explore." +** Module flags +- +lsp :: + Enable support for ~racket-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/jeapostrophe/racket-langserver][racket-langserver]]). +- +xp :: + Enable the explore mode (~racket-xp-mode~), which "analyzes expanded code to + explain and explore." -** Plugins -+ [[https://github.com/greghendershott/racket-mode][racket-mode]] +** Packages +- [[doom-package:][racket-mode]] -* Prerequisites -This module only requires ~racket~. Install it directly from the [[https://download.racket-lang.org/][racket website]], -or check your package manger. +** 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 ~racket~. Install it from the [[https://download.racket-lang.org/][racket website]] or through +your OS package manger. ** Arch Linux - -#+begin_src bash +#+begin_src sh pacman -S racket #+end_src Or, for fewer dependencies: - -#+begin_src bash +#+begin_src sh pacman -S racket-minimal #+end_src -* TODO Features +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** racket-smart-open-bracket-mode -~racket-smart-open-bracket-mode~ gets turned off automatically if you use ~parinfer~, -~lispy~. If you wish to enable it, add the following to your ~config.el~: -#+BEGIN_SRC elisp +~racket-smart-open-bracket-mode~ gets turned off automatically if you use +~parinfer~, ~lispy~. If you wish to enable it: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (after! racket-mode - (add-hook! racket-mode - #'racket-smart-open-bracket-mode)) -#+END_SRC + (add-hook 'racket-mode-hook #'racket-smart-open-bracket-mode)) +#+end_src + ** Unicode Input -The optional ~racket-unicode~ input method lets you type unicode characters such as Ξ» or Ο€. -To enable unicode input for a single buffer, run ~racket-unicode-input-method-enable~. -To enable unicode input by default on all racket buffers, add the following hooks -to your ~config.el~: -#+BEGIN_SRC elisp +The optional ~racket-unicode~ input method lets you type unicode characters such +as Ξ» or Ο€. To enable unicode input for a single buffer, run +~racket-unicode-input-method-enable~. To enable unicode input by default on all +racket buffers: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (add-hook 'racket-mode-hook #'racket-unicode-input-method-enable) (add-hook 'racket-repl-mode-hook #'racket-unicode-input-method-enable) -#+END_SRC -Once enabled, unicode input can be toggled by pressing C-\ or running ~toggle-input-method~. +#+end_src -* TODO Troubleshooting +Once enabled, unicode input can be toggled by pressing C-\ or running +~toggle-input-method~. + +* 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 diff --git a/modules/lang/raku/README.org b/modules/lang/raku/README.org index 337aebf1e..cb84a6779 100644 --- a/modules/lang/raku/README.org +++ b/modules/lang/raku/README.org @@ -1,11 +1,51 @@ -#+TITLE: :lang raku +# -*- mode: doom-docs-org -*- +#+title: :lang raku +#+subtitle: The artist formerly known as perl6 +#+created: June 05, 2020 +#+since: 21.12.0 (#3308) -This module adds a major mode and flycheck for Raku. +* Description :unfold: +This module adds support for the [[https://www.raku.org/][Raku programming language]] to Doom Emacs. -* Table of Contents :TOC: -- [[#install][Install]] +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -* Install -This module depends on raku itself. +** Module flags +/This module has no flags./ -There are no other dependencies. +** Packages +- [[doom-package:][raku-mode]] +- [[doom-package:][flycheck-raku]] if [[doom-module:][:checkers syntax]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires [[https://www.raku.org/][Raku]] for linting and evaluating code. + +* 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 diff --git a/modules/lang/rest/README.org b/modules/lang/rest/README.org index 1bc71dc08..ebe15bd26 100644 --- a/modules/lang/rest/README.org +++ b/modules/lang/rest/README.org @@ -1,58 +1,72 @@ -#+TITLE: lang/rest -#+DATE: March 17, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang rest +#+subtitle: Emacs as a REST client +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module turns Emacs into a [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] client. -* Description -This module adds [[https://en.wikipedia.org/wiki/Representational_state_transfer][REST]] support. - -+ Code-completion (~company-restclient~) -+ Code evaluation -+ Imenu support for ~restclient-mode~ -+ org-mode: babel support (~ob-restclient~) +- Code-completion (~company-restclient~) +- Code evaluation +- Imenu support for ~restclient-mode~ +- org-mode: babel support (~ob-restclient~) #+begin_quote -~restclient-mode~ is tremendously useful for automated or quick testing REST -APIs. My workflow is to open an ~org-mode~ buffer, create a restclient source -block and hack away. ~restclient-mode~ and ~company-restclient~ power this -arcane wizardry. + πŸ’‘ ~restclient-mode~ is tremendously useful for automated or quick testing REST + APIs. My workflow is to open an ~org-mode~ buffer, create a restclient + source block and hack away. ~restclient-mode~ and ~company-restclient~ power + this arcane wizardry. #+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/pashky/restclient.el][restclient]] -+ =:completion company= - + [[https://github.com/iquiw/company-restclient][company-restclient]] +** Module flags +- +jq :: + Enable native support for reading and processing REST responses with jq. + *Requires the =jq= command line utility.* + +** Packages +- [[doom-package:][company-restclient]] if [[doom-module:][:completion company]] +- [[doom-package:][restclient]] +- if [[doom-module:][+jq]] + - [[doom-package:][restclient-jq]] + - [[doom-package:][jq-mode]] ** Hacks -+ restclient has been modified not to silently reject self-signed or invalid +- Adds imenu support to ~restclient-mode~. +- [[doom-package:][restclient]] has been modified not to silently reject self-signed or invalid certificates. -+ Adds imenu support to ~restclient-mode~. -* Prerequisites -This module has no prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Features -# An in-depth list of features, how to use them, and their dependencies. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Configuration -# How to configure this module, including common problems and how to address them. +/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 -# Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/rst/README.org b/modules/lang/rst/README.org new file mode 100644 index 000000000..a91506247 --- /dev/null +++ b/modules/lang/rst/README.org @@ -0,0 +1,50 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang rst +#+subtitle: ReST in peace +#+created: October 15, 2021 +#+since: 21.12.0 + +* Description :unfold: +This module adds [[https://docutils.sourceforge.io/rst.html][ReStructured Text]] support to Doom Emacs. + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][sphinx-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.sphinx-doc.org/en/master/usage/installation.html][sphinx]] to build RST documents. + +* 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 diff --git a/modules/lang/ruby/README.org b/modules/lang/ruby/README.org index 58e33279b..5bfd4f251 100644 --- a/modules/lang/ruby/README.org +++ b/modules/lang/ruby/README.org @@ -1,91 +1,122 @@ -#+TITLE: lang/ruby -#+DATE: January 16, 2007 -#+SINCE: v1.3 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang ruby +#+subtitle: 1.step {|i| p "Ruby is #{i.even? ? 'love' : 'life'}"} +#+created: January 16, 2007 +#+since: 1.3 -* Table of contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#packages][Packages]] -- [[#prerequisites][Prerequisites]] - - [[#ubuntu][Ubuntu]] - - [[#macos][MacOS]] - - [[#windows][Windows]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] - -* Description +* Description :unfold: This module add Ruby and optional Ruby on Rails support to Emacs. -+ Code completion (robe) -+ Syntax checking (flycheck) -+ Jump-to-definitions (robe) -+ Bundler -+ Rubocop integration (flycheck) +- Code completion ([[doom-package:][robe]]) +- Syntax checking ([[doom-package:][flycheck]]) +- Jump-to-definitions ([[doom-package:][robe]]) +- Bundler +- Rubocop integration ([[doom-package:][flycheck]]) -** Module Flags -+ =+lsp= Enables LangServer support for ruby. You must have =:tools lsp= enabled - for this to work, as well as the langserver (solargraph) installed on your - system. -+ =+rvm= Enables RVM (Ruby Version Manager) integration. -+ =+rbenv= Enables rbenv integration. -+ =+chruby= Enables chruby integration. -+ =+rails= Enables rails navigational commands, plus server+console integration. +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +chruby :: + Enable chruby integration. +- +lsp :: + Enable LSP support for ~ruby-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports solargraph). +- +rails :: + Enable rails navigational commands, plus server+console integration. +- +rbenv :: + Enable rbenv integration. +- +rvm :: + Enable RVM (Ruby Version Manager) integration. +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. ** Packages -+ [[https://github.com/endofunky/bundler.el][bundler]] -+ [[https://github.com/plexus/chruby.el][chruby]] (=+chruby=) -+ [[https://github.com/company-mode/company-inf-ruby][company-inf-ruby]] -+ [[https://github.com/eschulte/jump.el][inflections]] -+ [[https://github.com/nonsequitur/inf-ruby][inf-ruby]] -+ [[https://github.com/arthurnn/minitest-emacs][minitest]] -+ [[https://github.com/asok/projectile-rails][projectile-rails]] (=+rails=) -+ [[https://github.com/asok/rake][rake]] -+ [[https://github.com/senny/rbenv.el][rbenv]] (=+rbenv=) -+ [[https://github.com/dgutov/robe][robe]] -+ [[https://github.com/pezra/rspec-mode][rspec-mode]] -+ [[https://github.com/rubocop-hq/rubocop-emacs][rubocop]] -+ [[https://github.com/senny/rvm.el][rvm]] (=+rvm=) +- [[doom-package:][bundler]] +- [[doom-package:][chruby]] if [[doom-module:][+chruby]] +- [[doom-package:][company-inf-ruby]] if :completion company +- [[doom-package:][inf-ruby]] +- [[doom-package:][minitest]] +- [[doom-package:][rake]] +- [[doom-package:][rbenv]] if [[doom-module:][+rbenv]] +- [[doom-package:][robe]] +- [[doom-package:][rspec-mode]] +- [[doom-package:][rubocop]] +- [[doom-package:][rvm]] if [[doom-module:][+rvm]] +- if [[doom-module:][+rails]] + - [[doom-package:][inflections]] + - [[doom-package:][projectile-rails]] -* Prerequisites -Many of this modules plugins require ruby with some version manager (RVM or -Rbenv) and the rubocop gem. +** Hacks +/No hacks documented for this module./ -** Ubuntu -You can follow [[https://gorails.com/setup/ubuntu/18.04][this guide]]. After ruby installation, run ~gem install rubocop~. -** MacOS -You can follow [[https://gorails.com/setup/osx/10.15-catalina][this guide]]. After ruby installation, run ~gem install rubocop~. -** Windows -You can follow [[https://gorails.com/setup/windows/10][this guide]]. After ruby installation, run ~gem install rubocop~. +** 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 Ruby and the Rubocop gem. It is recommended you install +both with some version manager (RVM or Rbenv). + +These guides will help you install Ruby: +- [[https://gorails.com/setup/ubuntu/18.04][Ubuntu]] +- [[https://gorails.com/setup/osx/10.15-catalina][MacOS]] +- [[https://gorails.com/setup/windows/10][Windows]] + +Then run ~$ gem install rubocop~ to install rubocop. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Appendix ** Commands *** robe -| command | key / ex command | description | -|----------------------+------------------+--------------------------------------------------------------------| -| ~robe-start~ | =SPC m \'= | Open ruby lang server for auto-completions and jump to definitions | -| ~robe-rails-refresh~ | =SPC m R= | Refresh the lang server. | +| command | key / ex command | description | +|----------------------+--------------------+--------------------------------------------------------------------| +| ~robe-start~ | [[kbd:][ ']] | Open ruby lang server for auto-completions and jump to definitions | +| ~robe-rails-refresh~ | [[kbd:][ R]] | Refresh the lang server. | *** projectile-rails -The projectile-rails prefix is =SPC m r=. Here is some examples: +The projectile-rails prefix is [[kbd:][ r]]: +| command | key / ex command | description | +|-------------------------------+-------------------+---------------------------------------------------| +| ~projectile-rails-console~ | [[kbd:][ r r]] | Open Rails console | +| ~projectile-rails-server~ | [[kbd:][ r R]] | Open Rails server | +| ~projectile-rails-find-model~ | [[kbd:][ r m]] | Find any model of the project | +| ~projectile-rails-find-model~ | [[kbd:][ r M]] | Find the model related of currently open resource | -| command | key / ex command | description | -|-------------------------------+------------------+---------------------------------------------------| -| ~projectile-rails-console~ | =SPC m r r= | Open Rails console | -| ~projectile-rails-server~ | =SPC m r R= | Open Rails server | -| ~projectile-rails-find-model~ | =SPC m r m= | Find any model of the project | -| ~projectile-rails-find-model~ | =SPC m r M= | Find the model related of currently open resource | *** bundler -The bundler prefix is =SPC m b=. Here is some examples: +The bundler prefix is [[kbd:][ b]]: +| command | key / ex command | description | +|------------------+-------------------+---------------------| +| ~bundle-install~ | [[kbd:][ b i]] | Runs bundle install | +| ~bundle-update~ | [[kbd:][ b u]] | Runs bundle update | -| command | key / ex command | description | -|------------------+------------------+---------------------| -| ~bundle-install~ | =SPC m b i= | Runs bundle install | -| ~bundle-update~ | =SPC m b u= | Runs bundle update | *** rspec-mode -The rspec-mode prefix is =SPC m t=. Here is some examples: -| | | | +The rspec-mode prefix is [[kbd:][ t]]: | command | key / ex command | description | |-----------------------+------------------+-----------------------------------| | ~rspec-verify~ | =SPC m t v= | Runs rspec on current file | | ~rspec-verify-method~ | =SPC m t s= | Runs rspec for the item on cursor | + +* 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 diff --git a/modules/lang/rust/README.org b/modules/lang/rust/README.org index f88d15f51..e4dff862f 100644 --- a/modules/lang/rust/README.org +++ b/modules/lang/rust/README.org @@ -1,139 +1,131 @@ -#+TITLE: lang/rust -#+DATE: June 5, 2019 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang rust +#+subtitle: Fe2O3.unwrap().unwrap().unwrap().unwrap() +#+created: September 30, 2015 +#+since: 0.7 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] - - [[#install][Install]] - - [[#arch-linux][Arch Linux]] - - [[#general][General]] - - [[#other-requirements][Other Requirements]] -- [[#features][Features]] - - [[#lsp-support-rls-or-rust-analyzer][LSP support (rls or rust-analyzer)]] - - [[#format-on-save][Format on save]] - - [[#keybinds][Keybinds]] -- [[#configuration][Configuration]] - - [[#enable-rls-by-default][Enable RLS by default]] - - [[#enabling-eglot-support-for-rust][Enabling eglot support for Rust]] -- [[#troubleshooting][Troubleshooting]] - - [[#errore0670-async-fn-is-not-permitted-in-the-2015-edition][error[E0670]: `async fn` is not permitted in the 2015 edition]] - -* Description +* Description :unfold: This module adds support for the Rust language and integration for its tools, e.g. ~cargo~. -+ Code completion (=racer= or an LSP server) -+ Syntax checking (=flycheck=) -+ LSP support (for rust-analyzer and rls) (=rustic=) -+ Snippets +- Code completion ([[doom-package:][racer]] or an LSP server) +- Syntax checking ([[doom-package:][flycheck]]) +- LSP support (for rust-analyzer and rls) ([[doom-package:][rustic]]) +- Snippets -** Module Flags -+ ~+lsp~ to add support Language server protocol. Will use the first of - =rust-analyzer= or =rls= (in that order). +** Maintainers +- @hlissner -** Plugins -+ [[https://github.com/brotzeit/rustic][rustic]] -+ [[https://github.com/racer-rust/emacs-racer][racer]]* (unless =+lsp=) +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~rustic-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports rust-analyzer and rls). + +** Packages +- [[doom-package:][rustic]] +- [[doom-package:][racer]] unless [[doom-module:][+lsp]] ** Hacks -+ rustic has been modified /not/ to automatically install lsp-mode or eglot if - they're missing. Doom expects you to have enabled the =:tools lsp= module +- rustic has been modified /not/ to automatically install lsp-mode or eglot if + they're missing. Doom expects you to have enabled the [[doom-module:][:tools lsp]] module yourself. -* Prerequisites +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -** Install - -This module requires ~rust~, which can be acquired through =rustup=. - -*** Arch Linux - -#+begin_src sh -sudo pacman -S rustup -#+end_src - -See also the Rust article [[https://wiki.archlinux.org/title/Rust#Rustup][on the Arch Wiki]]. - -Note that when the Rust /language/ has updates, you are to run =rustup= such that -it doesn't upgrade itself: - -#+begin_src sh -rustup update --no-self-update -#+end_src - -*** General +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] +This module requires ~rust~, which can be acquired through =rustup=: #+begin_src sh curl https://sh.rustup.rs -sSf | sh #+end_src +Note that when the Rust /language/ has updates, you are to run =rustup= such +that it doesn't upgrade itself: +#+begin_src sh +rustup update --no-self-update +#+end_src + ** Other Requirements - -Additional requirements depend on the module's configuration: - -+ If =:editor format= is enabled, you'll need =rustfmt=: ~rustup component add +- If [[doom-module:][:editor format]] is enabled, you'll need =rustfmt=: ~$ rustup component add rustfmt-preview~. -+ Users without =+lsp= enabled will need =racer=: ~cargo +nightly install racer~ +- Users without [[doom-module:][+lsp]] enabled will need [[doom-package:][racer]]: ~$ cargo +nightly install racer~ (with requires rust nightly edition). -+ Users with =+lsp= enabled will need: - + =rust-analyzer= or =rls= -+ Using the following commands requires: - + ~cargo-process-check~: ~cargo install cargo-check~ - + ~cargo-process-clippy~: ~rustup component add clippy-preview~ +- Users with [[doom-module:][+lsp]] enabled will need: + - =rust-analyzer= or =rls= +- Using the following commands requires: + - ~cargo-process-check~: ~$ cargo install cargo-check~ + - ~cargo-process-clippy~: ~$ rustup component add clippy-preview~ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** LSP support (rls or rust-analyzer) This module supports LSP integration. For it to work you'll need: 1. Either [[https://github.com/rust-analyzer/rust-analyzer][rust-analyzer]] or [[https://github.com/rust-lang/rls][the Rust Language Server]] installed (e.g. through your OS package manager). -2. The =:tools lsp= module enabled. -3. The ~+lsp~ flag on this module enabled. +2. The [[doom-module:][:tools lsp]] module enabled. +3. The [[doom-module:][+lsp]] flag on this module enabled. ** Format on save -Enable the [[file:../../../modules/editor/format/README.org][:editor format]] module's =+onsave= flag to get formatting on save with -rustfmt. No additional configuration is necessary. +Enable [[doom-module:][:editor format +onsave]] to get formatting on save with =rustfmt=. No +additional configuration is necessary. ** Keybinds | Binding | Description | |---------------------+-----------------------------| -| ~ b a~ | ~cargo audit~ | -| ~ b b~ | ~cargo build~ | -| ~ b B~ | ~cargo bench~ | -| ~ b c~ | ~cargo check~ | -| ~ b C~ | ~cargo clippy~ | -| ~ b d~ | ~cargo doc~ | -| ~ b n~ | ~cargo update~ | -| ~ b o~ | ~cargo outdated~ | -| ~ b r~ | ~cargo run~ | -| ~ t a~ | ~cargo test~ | -| ~ t t~ | ~run current test~ | +| = b a= | ~cargo audit~ | +| = b b= | ~cargo build~ | +| = b B= | ~cargo bench~ | +| = b c= | ~cargo check~ | +| = b C= | ~cargo clippy~ | +| = b d= | ~cargo doc~ | +| = b n= | ~cargo update~ | +| = b o= | ~cargo outdated~ | +| = b r= | ~cargo run~ | +| = t a= | ~cargo test~ | +| = t t= | ~run current test~ | * TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + ** Enable RLS by default If both =rls= and =rust-analyzer= are present on your system, =rust-analyzer= is -selected by default. Modify ~rustic-lsp-server~ to change the default: - -#+BEGIN_SRC elisp +used by default. Modify ~rustic-lsp-server~ to change the default: +#+begin_src emacs-lisp ;; in $DOOMDIR/config.el (after! rustic (setq rustic-lsp-server 'rls)) -#+END_SRC +#+end_src ** Enabling eglot support for Rust -Doom's =:tools lsp= module has an =+eglot= flag. Enable it and this module will -use eglot instead. +Doom's [[doom-module:][:tools lsp]] module has an [[doom-module:][+eglot]] flag. Enable it and this module will use +eglot instead. * Troubleshooting +[[doom-report:][Report an issue?]] + ** error[E0670]: `async fn` is not permitted in the 2015 edition You may be seeing this error, despite having ~edition = "2018"~ in your =Cargo.toml=. This error actually originates from ~rustfmt~, which the LSP -server tries to invoke on save (if you have ~rustic-format-on-save~ or =:editor -format= enabled). +server tries to invoke on save (if you have ~rustic-format-trigger~ or [[doom-module:][:editor +format]] enabled). To fix this your project needs a =rustfmt.toml= with ~edition = "2018"~ in it. + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/scala/README.org b/modules/lang/scala/README.org index 460c48ab4..bb56f6df8 100644 --- a/modules/lang/scala/README.org +++ b/modules/lang/scala/README.org @@ -1,57 +1,84 @@ -#+TITLE: lang/scala -#+DATE: October 14, 2020 -#+SINCE: v1.3 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang scala +#+subtitle: Java, but good +#+created: May 12, 2016 +#+since: 1.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] -- [[#lsp-integration][=+lsp= Integration]] - - [[#prerequisites][Prerequisites]] - - [[#coursier][Coursier]] - - [[#metals][Metals]] - - [[#features][Features]] - - [[#notes][Notes]] - -* Description +* Description :unfold: This module adds [[https://www.scala-lang.org][scala]] and [[https://www.scala-sbt.org/][sbt]] support to Doom Emacs. -** Module Flags -+ =+lsp= Enables integration for the metals LSP server. +Through the power of [[https://scalameta.org/metals/docs/editors/overview.html][Metals]] (LSP) this module offers: +- Goto Definition +- Completions +- Hover +- Paremeter Hints +- Find References +- Run/Debug +- Find Implementations +- Rename Symbol +- Code Actions +- Document Symbols +- Formatting +- Folding +- Organize Imports +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -* =+lsp= Integration +** Module flags +- +lsp :: + Enable LSP support for ~scala-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports metals). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -** Prerequisites +** Packages +- [[doom-package:][sbt-mode]] +- [[doom-package:][scala-mode]] +- [[doom-package:][lsp-metals]] if [[doom-module:][+lsp]] + +** 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.]] + +** =+lsp= Integration +To set up LSP support for Scala you'll need the Metals LSP server. To install it +you need Coursier installed first: *** Coursier -Note: Coursier is only required to install Metals. If system is running arch -linux this step can be safely skipped. +Coursier is only required to install Metals. If you're on Arch linux this step +can be skipped. **** Ubuntu / Debian / Fedora -#+BEGIN_SRC sh +#+begin_src sh curl -fLo cs https://git.io/coursier-cli-linux && chmod +x cs && ./cs -#+END_SRC +#+end_src **** MacOS -#+BEGIN_SRC sh +#+begin_src sh curl -fLo cs https://git.io/coursier-cli-macos && chmod +x cs && (xattr -d com.apple.quarantine cs || true) && ./cs -#+END_SRC +#+end_src -**** Arch -#+BEGIN_SRC sh +**** Arch Linux +#+begin_src sh yay -S coursier -#+END_SRC +#+end_src *** Metals - **** Ubuntu / Debian / Fedora / MacOS -Note: Update following command to latest version of metals [[https://scalameta.org/metals/docs/editors/emacs.html][found here]]. +Update following command to latest version of metals [[https://scalameta.org/metals/docs/editors/emacs.html][found here]]. #+begin_src sh coursier bootstrap \ @@ -64,31 +91,34 @@ coursier bootstrap \ -o /usr/local/bin/metals-emacs -f #+end_src -**** Arch -#+BEGIN_SRC sh +**** Arch Linux +#+begin_src sh yay -S metals -#+END_SRC +#+end_src -** Features -According to [[https://scalameta.org/metals/docs/editors/overview.html]] it adds +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -+ Goto Definition -+ Completions -+ Hover -+ Paremeter Hints -+ Find References -+ Run/Debug -+ Find Implementations -+ Rename Symbol -+ Code Actions -+ Document Symbols -+ Formatting -+ Folding -+ Organize Imports +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -** Notes +* Troubleshooting +[[doom-report:][Report an issue?]] -+ Projects are required to have scala version =2.11.12=, =2.12.8=, =2.13.0= or greater. -+ Latest version of sbt is recommended. -+ Running =M-x lsp-metals-doctor-run= helps diagnose problems. -+ Full reference here: https://scalameta.org/metals/docs/editors/emacs.html +- Projects are required to have scala version =2.11.12=, =2.12.8=, =2.13.0= or + greater. +- Latest version of sbt is recommended. +- Running ~M-x lsp-metals-doctor-run~ helps diagnose problems. +- Full reference here: https://scalameta.org/metals/docs/editors/emacs.html + +* 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 diff --git a/modules/lang/scheme/README.org b/modules/lang/scheme/README.org index 917a64f37..108f76e65 100644 --- a/modules/lang/scheme/README.org +++ b/modules/lang/scheme/README.org @@ -1,60 +1,82 @@ -#+TITLE: lang/scheme -#+DATE: July 23, 2019 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang scheme +#+subtitle: A fully conniving family of lisps +#+created: July 23, 2019 +#+since: 21.12.0 (#1588) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#commands][Commands]] - - [[#geiser][Geiser]] +* Description :unfold: +This module provides support for the Scheme family of Lisp languages, powered by +[[https://www.nongnu.org/geiser/geiser_1.html#introduction][geiser]]. -* Description -This module provides an environment for hacking and having fun in scheme. It is -powered by [[https://www.nongnu.org/geiser/geiser_1.html#introduction][geiser]]. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+chez= -+ =+chibi= -+ =+chicken= -+ =+gambit= -+ =+gauche= -+ =+guile= -+ =+kawa= -+ =+mit= -+ =+racket= +** Module flags +- +chez :: +- +chibi :: +- +chicken :: +- +gambit :: +- +gauche :: +- +guile :: +- +kawa :: +- +mit :: +- +racket :: -** Plugins -+ [[https://gitlab.com/jaor/geiser][geiser]] -+ [[https://github.com/nbfalcon/macrostep-geiser][macrostep-geiser]] -+ [[https://gitlab.com/emacs-geiser/chez][geiser-chez]] (if =+chez=) -+ [[https://gitlab.com/emacs-geiser/chibi][geiser-chibi]] (if =+chibi=) -+ [[https://gitlab.com/emacs-geiser/chicken][geiser-chicken]] (if =+chicken=) -+ [[https://gitlab.com/emacs-geiser/gambit][geiser-gambit]] (if =+gambit=) -+ [[https://gitlab.com/emacs-geiser/gauche][geiser-gauche]] (if =+gauche=) -+ [[https://gitlab.com/emacs-geiser/guile][geiser-guile]] (if =+guile=) -+ [[https://github.com/flatwhatson/flycheck-guile][flycheck-guile]] (if =+guile= and =:checkers syntax=) -+ [[https://gitlab.com/emacs-geiser/kawa][geiser-kawa]] (if =+kawa=) -+ [[https://gitlab.com/emacs-geiser/mit][geiser-mit]] (if =+mit=) -+ [[https://gitlab.com/emacs-geiser/racket][geiser-racket]] (if =+racket=) +** Packages +- [[doom-package:][flycheck-guile]] if [[doom-module:][+guile]] and [[doom-module:][:checkers syntax]] +- [[doom-package:][geiser]] +- [[doom-package:][geiser-chez]] if [[doom-module:][+chez]] +- [[doom-package:][geiser-chibi]] if [[doom-module:][+chibi]] +- [[doom-package:][geiser-chicken]] if [[doom-module:][+chicken]] +- [[doom-package:][geiser-gambit]] if [[doom-module:][+gambit]] +- [[doom-package:][geiser-gauche]] if [[doom-module:][+gauche]] +- [[doom-package:][geiser-guile]] if [[doom-module:][+guile]] +- [[doom-package:][geiser-kawa]] if [[doom-module:][+kawa]] +- [[doom-package:][geiser-mit]] if [[doom-module:][+mit]] +- [[doom-package:][geiser-racket]] if [[doom-module:][+racket]] +- [[doom-package:][macrostep-geiser]] -* Prerequisites -This module requires you to have at least one of the supported schemes, namely: +** 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.]] + +Depending on which flags you have enabled on this module, you'll need the +associated Schemes, namely: - [[https://www.gnu.org/software/guile][Guile]] 2.2.0 or better - [[https://call-cc.org][Chicken]] 4.8.0 or better - [[https://www.gnu.org/software/mit-scheme][MIT/GNU Scheme]] 9.1.1 or better - [[https://synthcode.com/scheme/chibi][Chibi Scheme]] 0.7.3 or better - [[https://www.scheme.com][Chez Scheme]] 9.4 or better -Their executables must be present in your path for geiser to work properly. +Their executables must be present in your =$PATH= for [[doom-package:][geiser]] to work properly. -* Features -** Commands -*** Geiser -| command | key / ex command | description | -|---------------------+------------------+----------------------| -| ~+scheme/open-repl~ | =:repl= | Open the Scheme Repl | -| | | | +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +| command | key / ex command | description | +|---------------------+-----------------------+----------------------| +| ~+scheme/open-repl~ | [[kbd:][ o r]], =:repl= | Open the Scheme Repl | + +* 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 diff --git a/modules/lang/sh/README.org b/modules/lang/sh/README.org index 8ce5159fb..5a94c007a 100644 --- a/modules/lang/sh/README.org +++ b/modules/lang/sh/README.org @@ -1,47 +1,73 @@ -#+TITLE: lang/sh -#+DATE: December 19, 2015 -#+SINCE: v0.7 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :lang sh +#+subtitle: She sells {ba,z,fi}sh shells on the C xor +#+created: September 28, 2015 +#+since: 0.7 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module adds support for shell scripting languages (including Powershell and +Fish script) to Doom Emacs. -* Description -This module adds support for shell scripting languages. +- Code completion ([[doom-package:][company-shell]]) +- Syntax Checking ([[doom-package:][flycheck]]) -+ Code completion (company-shell) -+ Syntax Checking (flycheck) +** Maintainers +- [[doom-user:][@hlissner]] -** Module Flags -+ =+lsp= Enables LSP support for sh-mode. This requires the =:tools lsp= module - to be enabled and [[https://github.com/mads-hartmann/bash-language-server][bash-language-server]] to be installed on your system. -+ =+fish= Add syntax highlighting for fish script files. -+ =+powershell= Add syntax highlighting for Powershell script files .ps1 and .psm1 +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +fish :: + Add syntax highlighting for fish script files. +- +lsp :: + Enable LSP support for ~sh-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports bash-language-server). +- +powershell :: + Add syntax highlighting for Powershell script files (=.ps1= and =.psm1=). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. -** Plugins -+ [[https://github.com/Alexander-Miller/company-shell][company-shell]]* (=:completion company=) -+ [[https://github.com/wwwjfy/emacs-fish][fish-mode]]* (=+fish=) -+ [[https://github.com/jschaf/powershell.el][powershell-mode]]* (=+powershell=) +** Packages +- [[doom-package:][company-shell]] if [[doom-module:][:completion company]] +- [[doom-package:][fish-mode]] if [[doom-module:][+fish]] +- [[doom-package:][powershell-mode]] if [[doom-module:][+powershell]] ** Hacks -+ Interpolated variables are fontified. +- Interpolated variables are fontified. + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites This module has several optional dependencies: -+ [[https://github.com/koalaman/shellcheck][shellcheck]]: Enables advanced shell script linting. -+ [[https://github.com/mads-hartmann/bash-language-server][bash-language-server]]: Enables LSP support (with =+lsp= flag). -+ With the =:tools debugger= module - + [[http://bashdb.sourceforge.net/][bashdb]]: Enables debugging for bash scripts - + [[https://github.com/rocky/zshdb][zshdb]]: Enables debugging for zsh scripts +- [[https://github.com/koalaman/shellcheck][shellcheck]]: Enables advanced shell script linting. +- [[https://github.com/mads-hartmann/bash-language-server][bash-language-server]]: Enables LSP support (with [[doom-module:][+lsp]] flag). +- With the [[doom-module:][:tools debugger]] module + - [[http://bashdb.sourceforge.net/][bashdb]]: Enables debugging for bash scripts + - [[https://github.com/rocky/zshdb][zshdb]]: Enables debugging for zsh scripts + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -* TODO Features * TODO Configuration -* TODO Troubleshooting +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/sml/README.org b/modules/lang/sml/README.org index 66543cda6..f29048f3f 100644 --- a/modules/lang/sml/README.org +++ b/modules/lang/sml/README.org @@ -1,39 +1,51 @@ -#+TITLE: lang/sml -#+DATE: March 29, 2020 -#+SINCE: v3.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang sml +#+subtitle: ... +#+created: Mar 30, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This module has no description yet. +* Description :unfold: +THis module adds [[https://smlfamily.github.io/][SML (Standard ML) programming language]] support to Doom Emacs. ** Maintainers -This module has no dedicated maintainers. +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ sml-mode -+ company-mlton (=:completion company=) +** Packages +- [[doom-package:][company-mlton]] if [[doom-module:][:completion company]] +- [[doom-package:][sml-mode]] -* TODO Prerequisites -# Document how to install sml program and MLton +** Hacks +/No hacks documented for this module./ -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires =sml= and =MLton=. + +* 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 diff --git a/modules/lang/solidity/README.org b/modules/lang/solidity/README.org index d91d419f3..77099c9db 100644 --- a/modules/lang/solidity/README.org +++ b/modules/lang/solidity/README.org @@ -1,47 +1,78 @@ -#+TITLE: :lang solidity +# -*- mode: doom-docs-org -*- +#+title: :lang solidity +#+subtitle: Do you need a blockchain? No. +#+created: May 19, 2018 +#+since: 21.12.0 (#599) -This module adds [[https://github.com/ethereum/solidity][Solidity]] support through [[https://github.com/ethereum/emacs-solidity][solidity-mode]] +* Description :unfold: +This module adds [[https://github.com/ethereum/solidity][Solidity]] support to Doom Emacs. -+ Syntax-checking (~flycheck~) -+ Code completion ([[https://github.com/ssmolkin1/company-solidity][company-solidity]]) -+ Gas estimation (~C-c C-g~) +- Syntax-checking ([[doom-package:][flycheck]]) +- Code completion ([[doom-package:][company-solidity]]) +- Gas estimation (~C-c C-g~) -* Table of Contents :TOC: -- [[#module-flags][Module Flags]] -- [[#prerequisites][Prerequisites]] - - [[#solc][Solc]] - - [[#solium][Solium]] -- [[#todo][TODO]] +** 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./ + +** Packages +- [[doom-package:][company-solidity]] if [[doom-module:][:completion company]] +- [[doom-package:][solidity-flycheck]] if [[doom-module:][:checkers syntax]] +- [[doom-package:][solidity-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.]] -* Prerequisites This module requires one or both linters for syntax checking: - -+ [[https://github.com/ethereum/solc-js][Solc]] -+ [[http://solium.readthedocs.io/en/latest/user-guide.html#installation][Solium]] +- [[https://github.com/ethereum/solc-js][Solc]] +- [[http://solium.readthedocs.io/en/latest/user-guide.html#installation][Solium]] If both are enabled *Solc* is run first, then *Solium* if *Solc* catches no errors. ** Solc -#+BEGIN_SRC sh +#+begin_src sh npm install -g solc -#+END_SRC +#+end_src ** Solium -#+BEGIN_SRC sh +#+begin_src sh npm install -g solium -#+END_SRC +#+end_src -By default *solium* looks for ~.soliumrc.json~ in the project directory, but you -can set it to your own ~.soliumrc.json~ with this in your private doom -~config.el~ - -#+BEGIN_SRC emacs-lisp +By default *solium* looks for =.soliumrc.json= in the project directory, but you +can set it to your own =.soliumrc.json= with: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq flycheck-solidity-solium-soliumrcfile "~/.soliumrc.json") -#+END_SRC +#+end_src -* TODO -+ Snippets +* 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 diff --git a/modules/lang/swift/README.org b/modules/lang/swift/README.org new file mode 100644 index 000000000..cd06936d0 --- /dev/null +++ b/modules/lang/swift/README.org @@ -0,0 +1,62 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang swift +#+subtitle: We asked for emoji variables? +#+created: June 15, 2015 +#+since: 0.7 + +* Description :unfold: +This module adds support for the [[https://developer.apple.com/swift/][Swift programming language]] to Doom Emacs. + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~swift-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports sourcekit). +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. + +** Packages +- [[doom-package:][swift-mode]] +- if [[doom-module:][+lsp]] + - [[doom-package:][lsp-sourcekit]] +- else + - [[doom-package:][company-sourcekit]] if [[doom-module:][:completion company]] + - [[doom-package:][flycheck-sourcekit]] if [[doom-module:][:checkers syntax]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote +πŸ”¨ /This module's prerequisites are not documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/terra/README.org b/modules/lang/terra/README.org new file mode 100644 index 000000000..12103e687 --- /dev/null +++ b/modules/lang/terra/README.org @@ -0,0 +1,53 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang terra +#+subtitle: Earth and Moon in alignment for performance. +#+created: March 25, 2019 +#+since: 21.12.0 (#1283) + +* TODO Description :unfold: +/(No description yet)/ + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][company-lua]] if [[doom-module:][:completion company]] +- [[doom-package:][terra-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./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote + πŸ”¨ /No installation steps have been documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* TODO Usage +#+begin_quote +πŸ”¨ This module 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 diff --git a/modules/lang/web/README.org b/modules/lang/web/README.org new file mode 100644 index 000000000..3ebae82c8 --- /dev/null +++ b/modules/lang/web/README.org @@ -0,0 +1,75 @@ +# -*- mode: doom-docs-org -*- +#+title: :lang web +#+subtitle: The tubes +#+created: June 15, 2015 +#+since: 0.7 + +* Description :unfold: +This module adds support for various web languages, including HTML5, CSS, +SASS/SCSS, Pug/Jade/Slim, and HAML, as well as various web frameworks, like +ReactJS, Wordpress, Jekyll, Phaser, AngularJS, Djano, and more. + +** Maintainers +- @hlissner + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +lsp :: + Enable LSP support for ~web-mode~ and ~css-mode~. Requires [[doom-module:][:tools lsp]] and a + langserver. +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. + +** Packages +- [[doom-package:][company-web]] if [[doom-module:][:completion company]] +- [[doom-package:][counsel-css]] if [[doom-module:][:completion ivy]] +- [[doom-package:][emmet-mode]] +- [[doom-package:][haml-mode]] +- [[doom-package:][helm-css-scss]] if [[doom-module:][:completion helm]] +- [[doom-package:][less-css-mode]] +- [[doom-package:][pug-mode]] +- [[doom-package:][rainbow-mode]] +- [[doom-package:][sass-mode]] +- [[doom-package:][slim-mode]] +- [[doom-package:][stylus-mode]] +- [[doom-package:][sws-mode]] +- [[doom-package:][web-mode]] + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +#+begin_quote + πŸ”¨ /No installation steps have been documented./ [[doom-contrib-module:][Document them?]] +#+end_quote + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/lang/yaml/README.org b/modules/lang/yaml/README.org index 3d3b7b9e9..8d4d93e21 100644 --- a/modules/lang/yaml/README.org +++ b/modules/lang/yaml/README.org @@ -1,38 +1,52 @@ -#+TITLE: lang/yaml -#+DATE: April 23, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang yaml +#+subtitle: JSON, but readable +#+created: April 24, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -This module provides support for the [[https://yaml.org/][YAML file format]]. +* Description :unfold: +This module provides support for the [[https://yaml.org/][YAML file format]] to Doom Emacs. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+lsp= Enables integration with LSP servers. Requires the =:tools lsp= module to be enabled. +** Module flags +- +lsp :: + Enable LSP support for ~yaml-mode~. Requires [[doom-module:][:tools lsp]] and a langserver + (supports [[https://github.com/redhat-developer/yaml-language-server][yaml-language-server]]). -** Plugins -+ [[https://github.com/yoshiki/yaml-mode][yaml-mode]] +** Packages +- [[doom-package:][yaml-mode]] -* Prerequisites -This module has no prerequisites. +** Hacks +/No hacks documented for this module./ -* TODO Features -# An in-depth list of features, how to use them, and their dependencies. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Configuration -# How to configure this module, including common problems and how to address them. +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote * TODO Troubleshooting -# Common issues and their solution, or places to look for help. +/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 diff --git a/modules/lang/zig/README.org b/modules/lang/zig/README.org index da69d1b32..59fef6401 100644 --- a/modules/lang/zig/README.org +++ b/modules/lang/zig/README.org @@ -1,66 +1,88 @@ -#+TITLE: lang/zig -#+DATE: March 18, 2021 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :lang zig +#+subtitle: C, but simpler +#+created: April 05, 2021 +#+since: 21.12.0 (#4827) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#lsp-support][LSP support]] - - [[#keybinds][Keybinds]] -- [[#configuration][Configuration]] - - [[#customize-zls-path][Customize zls path]] - -* Description +* Description :unfold: This module adds [[https://ziglang.org/][Zig]] support, with optional (but recommended) LSP support via [[https://github.com/zigtools/zls][zls]]. -+ Syntax highlighting -+ Syntax-checking (~flycheck~) -+ Code completion and LSP integration (~zls~) +- Syntax highlighting +- Syntax-checking ([[doom-package:][flycheck]]) +- Code completion and LSP integration (~zls~) ** Maintainers -+ [[https://github.com/bnjmnt4n][@bnjmnt4n]] (Author) +- [[doom-user:][@bnjmnt4n]] -** Module Flags -+ =+lsp= Enables integration for the zls LSP server. It is highly recommended - you use this. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/ziglang/zig-mode][zig-mode]] +** Module flags +- +lsp :: + Enables integration for the zls LSP server. It is highly recommended you use + this. +- +tree-sitter :: + Leverages tree-sitter for better syntax highlighting and structural text + editing. Requires [[doom-module:][:tools tree-sitter]]. + +** Packages +- [[doom-package:][zig-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.]] -* Prerequisites To get started with Zig, you need the ~zig~ tool. Pre-built binaries for most systems are available for download from [[https://ziglang.org/download/]] or from [[https://github.com/ziglang/zig/wiki/Install-Zig-from-a-Package-Manager][system package managers]]. -zls is a language server for Zig, which provides code completion, +=zls= is a language server for Zig, which provides code completion, + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** LSP support This module supports LSP integration. For it to work you'll need: -1. zls installed. -2. The =:tools lsp= module enabled. Only =lsp-mode= is supported for now. -3. The ~+lsp~ flag on this module enabled. +1. zls installed, +2. The [[doom-module:][:tools lsp]] module enabled. Only [[doom-package:][lsp-mode]] is supported for now, +3. The [[doom-module:][+lsp]] flag on this module enabled. ** Keybinds | Binding | Description | |-------------------+---------------------| -| ~ b~ | ~zig-compile~ | -| ~ f~ | ~zig-format-buffer~ | -| ~ r~ | ~zig-run~ | -| ~ t~ | ~zig-test-buffer~ | +| [[kbd:][ b]] | ~zig-compile~ | +| [[kbd:][ f]] | ~zig-format-buffer~ | +| [[kbd:][ r]] | ~zig-run~ | +| [[kbd:][ t]] | ~zig-test-buffer~ | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Customize zls path -To customize the path of the =zls= executable, modify ~lsp-zig-zls-executable~. - -#+BEGIN_SRC elisp +To customize the path of the =zls= executable, modify ~lsp-zig-zls-executable~: +#+begin_src emacs-lisp ;; in $DOOMDIR/config.el (setq lsp-zig-zls-executable "~/path/to/zls") -#+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 diff --git a/modules/os/README.org b/modules/os/README.org new file mode 100644 index 000000000..7d1cee3a3 --- /dev/null +++ b/modules/os/README.org @@ -0,0 +1,11 @@ +# -*- mode: doom-docs-org -*- +#+title: :os +#+created: November 03, 2021 +#+since: 21.12.0 + +* Description +Modules in this category are designed to improve compatibility with certain +operating systems or OS features (like the shell). + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/os/macos/README.org b/modules/os/macos/README.org index bbe296e57..2b6ba0981 100644 --- a/modules/os/macos/README.org +++ b/modules/os/macos/README.org @@ -1,36 +1,45 @@ -#+TITLE: os/macos -#+DATE: February 19, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :os macos +#+subtitle: Compatibility for our favorite walled garden +#+created: February 19, 2017 +#+since: 1.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#maintainers][Maintainers]] - - [[#plugins][Plugins]] -- [[#features][Features]] - - [[#open-with-x]["Open with X"]] - -* Description +* Description :unfold: This module provides extra functionality for macOS. -** Module Flags -This module provides no flags. - ** Maintainers -This module has no dedicated maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/emacsorphanage/osx-trash][osx-trash]] -+ [[https://github.com/purcell/ns-auto-titlebar][ns-auto-titlebar]] +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][ns-auto-titlebar]] +- [[doom-package:][osx-trash]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires a macOS environment. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** "Open with X" -This module adds various macOS-specific launchers under the =SPC o= prefix (=C-c -o= for users with Evil disabled). +This module adds various macOS-specific launchers under the [[kbd:][SPC o]] prefix ([[kbd:][C-c +o]] for users with Evil disabled). -It also enables Keychain integration for =auth-source=. This is used by our [[file:../../../modules/app/irc/README.org][irc]] -and [[file:../../../modules/tools/magit/README.org][magit]]-forge modules, for instance. +It also enables Keychain integration for [[doom-package:][auth-source]]. This is used by our [[doom-module:][:app +irc]] and [[doom-module:][:tools magit]] modules, for instance. To support GitHub Forge add an internet password like this to your keychain: | Field | Value | @@ -40,3 +49,19 @@ To support GitHub Forge add an internet password like this to your keychain: | Account | ^forge | | Where | https://api.github.com/ | | Password | | + +* 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 diff --git a/modules/os/tty/README.org b/modules/os/tty/README.org index b18ce9434..e21220081 100644 --- a/modules/os/tty/README.org +++ b/modules/os/tty/README.org @@ -1,66 +1,81 @@ -#+TITLE: os/tty -#+DATE: August 7, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :os tty +#+subtitle: Make TTY Emacs suck less +#+created: August 07, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] - - [[#true-color-and-italic-support][True-color and italic support]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module configures Emacs for use in the terminal, by providing: -+ System clipboard integration (through an external clipboard program or OSC-52 +- System clipboard integration (through an external clipboard program or OSC-52 escape codes in supported terminals). -+ Cursor-shape changing across evil states (requires a terminal that supports +- Cursor-shape changing across evil states (requires a terminal that supports it). -+ Mouse support in the terminal. +- Mouse support in the terminal. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+osc= Instead of piping your kill ring through external programs, like xclip - or pbcopy, have Emacs emit OSC-52 escape codes instead, allowing Emacs to +** Module flags +- +osc :: + Instead of piping your kill ring through external programs, like =xclip= or + =pbcopy=, have Emacs emit OSC-52 escape codes instead, allowing Emacs to communicate with your clipboard through your terminal, even across SSH connections or Tmux. However, this requires [[https://github.com/spudlyo/clipetty#terminals-that-support-osc-clipboard-operations][a supported terminal]]. -** Plugins -+ [[https://github.com/spudlyo/clipetty][clipetty]]* (if =+osc=) -+ [[https://github.com/7696122/evil-terminal-cursor-changer][evil-terminal-cursor-changer]]* (if =:editor evil=) -+ [[https://github.com/emacs-straight/xclip][xclip]]* (unless =+osc=) +** Packages +- [[doom-package:][clipetty]] if [[doom-module:][+osc]] +- [[doom-package:][evil-terminal-cursor-changer]] if [[doom-module:][:editor evil]] +- [[doom-package:][xclip]] unless [[doom-module:][+osc]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites This module has no hard prerequisites, but in order for its features to work you need: -+ For system clipboard integration: - + A supported clipboard program, such as: - + Linux: =xclip=, =xsel=, or =wl-clibpoard= (Wayland) - + macOS: =pbcopy= and =pbpaste= (included with macOS) - + Windows: =getclip= and =putclip= (cygwin) - + (If =+osc= is enabled) A terminal that supports OSC 52 escape codes, such - as: xterm (unix), iTerm2 (macOS), alacritty (cross platform), kitty (macOS, +- For system clipboard integration: + - A supported clipboard program, such as: + - Linux: =xclip=, =xsel=, or =wl-clibpoard= (Wayland) + - macOS: =pbcopy= and =pbpaste= (included with macOS) + - Windows: =getclip= and =putclip= (cygwin) + - (If [[doom-module:][+osc]] is enabled) A terminal that supports OSC 52 escape codes, such as: + xterm (unix), iTerm2 (macOS), alacritty (cross platform), kitty (macOS, linux), mintty (Windows), hterm (javascript), st (unix), mlterm (cross platform) -+ For cursor shape changing in the terminal you need A terminal that supports +- For cursor shape changing in the terminal you need A terminal that supports VT's DECSCUSR sequence, such as: Gnome Terminal, xterm, iTerm (macOS), Konsole, or mintty (Windows). Terminal.app (macOS) is supported too, but requires [[http://www.culater.net/software/SIMBL/SIMBL.php][SIMBL]] and [[https://github.com/saitoha/mouseterm-plus/releases][MouseTerm]] Plus to work. -* Configuration -** True-color and italic support -Emacs 26.3 users should consult [[https://github.com/syl20bnr/spacemacs/wiki/Terminal][the spacemacs wiki]] for details on achieving true -color support in terminal Emacs. +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote -Emacs 27.x users don't need todo anything, as true color support is [[https://github.com/emacs-mirror/emacs/commit/7f6153d9563cfe7753083996f59eacc9f4c694df][built into -27.1+ and newer]]. +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +** True-color and italic support +Consult [[https://github.com/syl20bnr/spacemacs/wiki/Terminal][the spacemacs wiki]] for details on achieving true color support for +terminal Emacs. * Troubleshooting -# Common issues and their solution, or places to look for help. +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/term/README.org b/modules/term/README.org new file mode 100644 index 000000000..63e5d5ed1 --- /dev/null +++ b/modules/term/README.org @@ -0,0 +1,16 @@ +# -*- mode: doom-docs-org -*- +#+title: :term +#+created: August 01, 2021 +#+since: 21.12.0 + +* Description +What's an operating system without a terminal? The modules in this category +bring varying degrees of terminal emulation into Emacs. + +If you can't decide which to choose, I recommend [[doom-package:][vterm]] or [[doom-package:][eshell]]. [[doom-module:][:term vterm]] +offers that best terminal emulation available but requires a few extra steps to +get going. [[doom-module:][:term eshell]] works everywhere that Emacs runs, even Windows, and +provides a shell entirely implemented in Emacs Lisp. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/term/eshell/README.org b/modules/term/eshell/README.org index 066a71f46..5d46b2f57 100644 --- a/modules/term/eshell/README.org +++ b/modules/term/eshell/README.org @@ -1,65 +1,76 @@ -#+TITLE: term/eshell -#+DATE: May 18, 2020 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :term eshell +#+subtitle: The elisp shell that works everywhere +#+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]] - - [[#term-name][TERM name]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module provides additional features for the built-in [[https://www.gnu.org/software/emacs/manual/html_mono/eshell.html][Emacs Shell]] -The Emacs Shell or =eshell= is a shell-like command interpreter implemented in +The Emacs Shell or [[doom-package:][eshell]] is a shell-like command interpreter implemented in Emacs Lisp. It is an alternative to traditional shells such as =bash=, =zsh=, =fish=, etc. that is built into Emacs and entirely cross-platform. ** Maintainers -This module has no dedicated maintainers. +- [[doom-user:][@hlissner]] -** Module Flags -This module provides no flags, but does gain auto-completion if =:completion -company= is enabled. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/peterwvj/eshell-up][eshell-up]] -+ [[https://github.com/xuchunyang/eshell-z][eshell-z]] -+ [[https://github.com/tom-tan/esh-help][esh-help]] -+ [[https://gitlab.com/bennya/shrink-path.el][shrink-path]] -+ [[https://github.com/xuchunyang/eshell-did-you-mean][eshell-did-you-mean]] -+ =:completion company= - + [[https://gitlab.com/ambrevar/emacs-fish-completion][fish-completion]] - + [[https://github.com/szermatt/emacs-bash-completion][bash-completion]] +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][eshell-did-you-mean]] +- [[doom-package:][eshell-up]] +- [[doom-package:][eshell-z]] +- [[doom-package:][esh-help]] +- [[doom-package:][shrink-path]] +- if [[doom-module:][:completion company]] + - [[doom-package:][fish-completion]] + - [[doom-package:][bash-completion]] ** Hacks -+ Even with =fish-completion-fallback-on-bash-p= non-nil, fish must be installed - for bash completion to work. Workaround in =config.el=. -+ =eshell-did-you-mean= does not work on first invocation, so we manually invoke +- Even with ~fish-completion-fallback-on-bash-p~ non-nil, fish must be installed + for bash completion to work. This has been circumvented. +- [[doom-package:][eshell-did-you-mean]] does not work on first invocation, so we manually invoke it once. -* Prerequisites -[[https://fishshell.com/][=fish= shell]] for completions, falling back to [[https://www.gnu.org/software/bash/][=bash= shell]] if =fish= is not -found. If neither shell is found, completions may not be available. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Features -+ Command completion with Company -+ =fish=-style prompt with Git integration -+ [[https://github.com/rupa/z][=z=]]-like directory jumping -+ Command-not-found recommendations +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires either [[https://fishshell.com/][Fish shell]] or [[https://www.gnu.org/software/bash/][Bash]] for code completion. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +- Command completion with Company +- =fish=-style prompt with Git integration +- [[https://github.com/rupa/z][=z=]]-like directory jumping +- Command-not-found recommendations + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** TERM name -By default, =eshell= sets the =$TERM= variable to ="xterm-256color"=, which helps with -rendering various colours. As eshell is /not/ a terminal emulator, these will not -always work 100%. Modifying =eshell-term-name= to your liking may help. +By default, [[doom-package:][eshell]] sets the =$TERM= variable to ~"xterm-256color"~, which helps +with rendering various colours. As eshell is /not/ a terminal emulator, these +will not always work 100%. Modifying ~eshell-term-name~ to your liking may help. -* 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 diff --git a/modules/term/shell/README.org b/modules/term/shell/README.org new file mode 100644 index 000000000..77268174e --- /dev/null +++ b/modules/term/shell/README.org @@ -0,0 +1,61 @@ +# -*- mode: doom-docs-org -*- +#+title: :term shell +#+subtitle: A REPL for your shell +#+created: August 01, 2021 +#+since: 21.12.0 + +* Description :unfold: +Provides a REPL for your shell. + +#+begin_quote + πŸ’‘ =shell= is more REPL than terminal emulator. You can edit your command line + like you would any ordinary text in Emacs -- something you can't do in [[doom-package:][term]] + (without ~term-line-mode~, which can be unstable) or [[doom-package:][vterm]]. + + Due to =shell='s simplicity, you're less likely to encounter edge cases + (e.g. against your shell config), but it's also the least capable. TUI + programs like =htop= or =vim= won't work in shell directly, but will be + launched in a =term= buffer -- which handles them reasonably well. +#+end_quote + +** 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 diff --git a/modules/term/term/README.org b/modules/term/term/README.org new file mode 100644 index 000000000..b5b25c856 --- /dev/null +++ b/modules/term/term/README.org @@ -0,0 +1,50 @@ +# -*- mode: doom-docs-org -*- +#+title: :term term +#+subtitle: It's terminal +#+created: August 01, 2021 +#+since: 21.12.0 + +* Description :unfold: +/(No description)/ + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][multi-term]] + +** 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 diff --git a/modules/term/vterm/README.org b/modules/term/vterm/README.org index 7be253d72..63fa2656e 100644 --- a/modules/term/vterm/README.org +++ b/modules/term/vterm/README.org @@ -1,33 +1,50 @@ -#+TITLE: term/vterm -#+DATE: January 16, 2019 -#+SINCE: 2.1 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :term vterm +#+subtitle: As good as terminal emulation gets in Emacs +#+created: January 16, 2019 +#+since: 21.12.0 (#1144) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#dynamic-module-support][Dynamic Module support]] - - [[#libvterm][libvterm]] - - [[#compilation-tools-for-vterm-moduleso][Compilation tools for vterm-module.so]] - -* Description +* Description :unfold: This module provides a terminal emulator powered by libvterm. It is still in alpha and requires a component be compiled (=vterm-module.so=). -The following commands are available to open it: +#+begin_quote + πŸ’‘ [[doom-package:][vterm]] is as good as terminal emulation gets in Emacs (at the time of + writing) and the most performant, as it is implemented in C. However, it + requires extra steps to set up: -+ ~+vterm/toggle~ (=SPC o t=): Toggle vterm pop up window in the current project -+ ~+vterm/here~ (=SPC o T=): Opens vterm in the current window + - Emacs must be built with dynamic modules support, + - and =vterm-module.so= must be compiled, which depends on =libvterm=, + =cmake=, and =libtool-bin=. -** Module Flags -This module provides no flags. + [[doom-package:][vterm]] will try to automatically build =vterm-module.so= when you first open + it, but this will fail on Windows, NixOS and Guix out of the box. Install + instructions for nix/guix can be found in the [[doom-module:][:term vterm]] module's + documentation. There is no way to install vterm on Windows that I'm aware of + (but perhaps with WSL?). +#+end_quote -** Plugins -+ [[https://github.com/akermu/emacs-libvterm][vterm]] +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][vterm]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Prerequisites + Emacs must be built with dynamic module support, i.e. compiled with the =--with-modules= option. + You need =libvterm= installed on your system. @@ -35,12 +52,12 @@ This module provides no flags. build =vterm-module.so=. ** Dynamic Module support -To check if your build of Emacs was built with dynamic module support, check -~bin/doom info~ for ~MODULES~ next to "System features". If it's there, you're -good to go. +To check if your build of Emacs was built with dynamic module support, check ~$ +doom info~ for ~MODULES~ next to "System features". If it's there, you're good +to go. -You can also check for =--with-modules= in the ~system-configuration-options~ -variable (=SPC h v system-configuration-options=). +You can also check for ~--with-modules~ in the ~system-configuration-options~ +variable ([[kbd:][SPC h v system-configuration-options]]). - Archlinux or Manjaro users who installed Emacs through pacman will have support baked in. @@ -48,76 +65,103 @@ variable (=SPC h v system-configuration-options=). - If you use [[https://emacsformacosx.com/][Emacs For Mac OS X]], this option is enabled. - If you use [[https://github.com/d12frosted/homebrew-emacs-plus][emacs-plus]], this option is enabled by default. - If you use [[https://github.com/railwaycat/homebrew-emacsmacport][emacs-mac]], this options is *not* enabled by default. You may have - to reinstall emacs with the option: ~brew install emacs-mac --with-modules~ + to reinstall emacs with the option: ~$ brew install emacs-mac + --with-modules~. ** libvterm -+ Ubuntu or Debian users: ~apt-get install libvterm-dev~ -+ ArchLinux or Manjaro: ~pacman -S libvterm~ -+ MacOS: ~libvterm~ -+ NixOS: +- Ubuntu or Debian users: ~$ apt-get install libvterm-dev~ +- ArchLinux or Manjaro: ~$ pacman -S libvterm~ +- MacOS: ~$ brew install libvterm~ +- NixOS: - #+BEGIN_SRC nix + #+begin_src nix systemPackages = with pkgs; [ # emacs # no need for this, the next line includes emacs - ((emacsPackagesNgGen emacs).emacsWithPackages (epkgs: [ + ((emacsPackagesFor emacs).emacsWithPackages (epkgs: [ epkgs.vterm ])) ]; - #+END_SRC + #+end_src Or for home-manager users: - - #+BEGIN_SRC nix + #+begin_src nix programs.emacs = { enable = true; extraPackages = epkgs: [ epkgs.vterm ]; }; - #+END_SRC + #+end_src - This already contains a version of =vterm-module.so=, so NixOS users need - not compile the module themselves as described below. + This already contains a version of =vterm-module.so=, so NixOS users need not + compile the module themselves as described below. - Note: The =nixpkgs=-version that is used needs to be compatible with the rest - of the plugins installed in =doom=. Therefore it might be necessary to pull in - =emacs= and/or =emacsPackagesNgGen= from =unstable= or another channel. Otherwise - arbitrary functionality of =vterm= might not work. + Note: The =nixpkgs=-version used must be compatible with the packages Doom + installs, so it might be necessary to pull in =emacs= and/or + =emacsPackagesFor= from =unstable= or another channel. Otherwise arbitrary + functionality of =vterm= might not work. ** Compilation tools for vterm-module.so When you first load vterm, it will compile =vterm-module.so= for you. For this to succeed, you need the following: -+ =make= -+ =cmake= -+ A C compiler like =gcc= -+ An internet connection (=cmake= will download needed libraries) +- =make= +- =cmake= +- A C compiler like =gcc= +- An internet connection (=cmake= will download needed libraries) There are several ways to manually install the module: -1. You can use =M-x vterm-module-compile= to let emacs automatically compile and +1. You can use ~M-x vterm-module-compile~ to let emacs automatically compile and install the module. Modify ~vterm-module-cmake-args~ to pass arguments to the cmake build script. - e.g. To use a local build of libvterm instead of the included one. - - #+BEGIN_SRC elisp + e.g. To use a local build of libvterm instead of the included one: + #+begin_src emacs-lisp (setq vterm-module-cmake-args "-DUSE_SYSTEM_LIBVTERM=yes") - #+END_SRC + #+end_src - *WARNING*: Emacs will hang during the compilation. It may take a while. + #+begin_quote + 🚧 Emacs will hang during the compilation. It may take a while. + #+end_quote 2. You can compile and install the module yourself. Go to the vterm installation - directory (usually =~/.emacs.d/.local/packages/elpa/vterm-=) and run - the following: - - #+BEGIN_SRC sh + directory (usually =$HOME/.emacs.d/.local/packages/elpa/vterm-=) and + run the following: + #+begin_src sh mkdir -p build cd build cmake -DCMAKE_BUILD_TYPE=RelWithDebInfo .. make - #+END_SRC + #+end_src 3. You can also compile =vterm-module.so= elsewhere, but the module must be moved/symlinked to - =~/.emacs.d/.local/packages/elpa/vterm-/vterm-module.so= + =$HOME/.emacs.d/.local/packages/elpa/vterm-/vterm-module.so= =vterm-module.so=. Keep in mind that this folder will be deleted whenever the vterm package is updated. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +The following commands are available to open it: + +- ~+vterm/toggle~ ([[kbd:][ o t]]) -- Toggle vterm pop up window in the current + project. +- ~+vterm/here~ ([[kbd:][ o T]]) -- Opens vterm in the current window. + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/tools/README.org b/modules/tools/README.org new file mode 100644 index 000000000..e7c34bf3e --- /dev/null +++ b/modules/tools/README.org @@ -0,0 +1,10 @@ +# -*- mode: doom-docs-org -*- +#+title: :tools +#+created: July 29, 2021 +#+since: 21.12.0 + +* Description +Modules that integrate external tools into Emacs. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/tools/ansible/README.org b/modules/tools/ansible/README.org new file mode 100644 index 000000000..28743f4a5 --- /dev/null +++ b/modules/tools/ansible/README.org @@ -0,0 +1,54 @@ +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/debugger/README.org b/modules/tools/debugger/README.org new file mode 100644 index 000000000..5c783307b --- /dev/null +++ b/modules/tools/debugger/README.org @@ -0,0 +1,168 @@ +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/direnv/README.org b/modules/tools/direnv/README.org index 388751d83..7416eb1a7 100644 --- a/modules/tools/direnv/README.org +++ b/modules/tools/direnv/README.org @@ -1,76 +1,97 @@ -#+TITLE: tools/direnv -#+DATE: July 10, 2019 -#+SINCE: v2.1.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/docker/README.org b/modules/tools/docker/README.org index ddf9eec07..c40f6177c 100644 --- a/modules/tools/docker/README.org +++ b/modules/tools/docker/README.org @@ -1,139 +1,149 @@ -#+TITLE: tools/docker -#+DATE: April 30, 2019 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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 +#+end_example -#+BEGIN_EXAMPLE -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 diff --git a/modules/tools/editorconfig/README.org b/modules/tools/editorconfig/README.org index 0a80a5471..e3aafbeea 100644 --- a/modules/tools/editorconfig/README.org +++ b/modules/tools/editorconfig/README.org @@ -1,46 +1,43 @@ -#+TITLE: tools/editorconfig -#+DATE: August 22, 2020 -#+SINCE: 2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+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 +45,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 +64,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 diff --git a/modules/tools/ein/README.org b/modules/tools/ein/README.org index 6f3d40cdc..7d46e8ad7 100644 --- a/modules/tools/ein/README.org +++ b/modules/tools/ein/README.org @@ -1,26 +1,54 @@ -#+TITLE: tools/ein -#+DATE: April 11, 2018 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/eval/README.org b/modules/tools/eval/README.org index 17f33fd54..936aba51f 100644 --- a/modules/tools/eval/README.org +++ b/modules/tools/eval/README.org @@ -1,73 +1,78 @@ -#+TITLE: tools/eval -#+DATE: February 13, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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 +84,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 +105,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 diff --git a/modules/tools/gist/README.org b/modules/tools/gist/README.org new file mode 100644 index 000000000..732ebfec2 --- /dev/null +++ b/modules/tools/gist/README.org @@ -0,0 +1,56 @@ +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/lookup/README.org b/modules/tools/lookup/README.org index 7800e7101..6ae20a9cb 100644 --- a/modules/tools/lookup/README.org +++ b/modules/tools/lookup/README.org @@ -1,74 +1,72 @@ -#+TITLE: tools/lookup -#+DATE: January 4, 2018 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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 +75,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 +103,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,36 +141,41 @@ 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 +You can install dash docsets with ~M-x dash-docs-install-docset~ and search them offline with ~M-x +lookup/in-docsets~, or with ~+lookup/documentation~ in 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 - ~+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. +- ~: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 [[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 +188,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,31 +197,30 @@ 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 -docsets must be installed with ~dash-docset-install-docset~. +docsets must be installed with ~dash-docs-install-docset~. ** Open in eww instead of browser ~+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 +228,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~ diff --git a/modules/tools/lsp/README.org b/modules/tools/lsp/README.org index 4dfefa79b..d70a0ae8c 100644 --- a/modules/tools/lsp/README.org +++ b/modules/tools/lsp/README.org @@ -1,81 +1,76 @@ -#+TITLE: tools/lsp -#+DATE: March 05, 2019 -#+SINCE: v2.1 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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,37 +79,78 @@ 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 : -| Keybind | Description | -|-----------+-------------------------------------| -| =SPC c j= | Jump to symbol in current workspace | -| =SPC c J= | Jump to symbol in any workspace | +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 | +|---------+-------------------------------------| +| [[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 -easy way to switch out lsp client implementations so you can test for yourself -which one you prefer. +The two projects are large and actively developed, so without writing a novel, +it can only be compared in (very) broad strokes: -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=, ...). +- [[doom-package:][lsp-mode]] tends to be more featureful, beginner-friendly (e.g. offers to + install servers for you and has more [[https://emacs-lsp.github.io/lsp-mode][helpful documentation]]), and has a user + experience that feels familiar to modern editors/IDEs, but at the cost of + performance (at baseline) and complexity (it has more moving parts and + reinvents a number of wheels to achieve a slicker UI, like ~lsp-ui-peek~, + ~lsp-ui-sideline~, etc). + +- [[doom-package:][eglot]] has fewer bells and whistles: it relies on built-in Emacs functionality + more (eldoc, xref, capf, project.el, etc), offers less pre-configuration for + you, and is more performant than lsp-mode (again, at baseline). It also works + with TRAMP out-of-the-box (lsp-mode needs some extra configuration). + +#+begin_quote + πŸ•ž I recommend beginners use lsp-mode. More experienced users can can disable + many of [[https://emacs-lsp.github.io/lsp-mode/tutorials/how-to-turn-off/][its inessential features]] to gain back some ground on performance and + complexity costs. +#+end_quote + +All that said, it's easy to switch between the two implementations by swapping +in/out the [[doom-module:][+lsp]] or [[doom-module:][+eglot]] flag when [[id:01cffea4-3329-45e2-a892-95a384ab2338][enabling this module]]. * 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 + +** LSP is slow +Follow [[https://emacs-lsp.github.io/lsp-mode/page/performance/#tuning][lsp-tuning-guide]] to further fine-tune LSP mode performance. + +* 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 diff --git a/modules/tools/magit/README.org b/modules/tools/magit/README.org index 1525e772d..c15a2eb44 100644 --- a/modules/tools/magit/README.org +++ b/modules/tools/magit/README.org @@ -1,78 +1,101 @@ -#+TITLE: tools/magit -#+DATE: March 14, 2018 -#+SINCE: v2.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+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:][code-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]] +- [[doom-package:][code-review]] will also require a token setup (see [[https://github.com/wandersoncferreira/code-review#configuration][configuration]] for your particular forge) + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +Start magit with [[kbd:][ 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 +** "I recently updated and now I get 'deferred error : (wrong-type-argument sequencep code-review--auth-token-set\?)' whenever I try to review'" +The previous package "github-review" was replaced with a package that supercedes it called "code-review", which requires a simple change in your authinfo file. + +#+begin_src authinfo +machine api.github.com login yourlogin^github-review password MYTOKENGOESHERE +#+end_src + +becomes + +#+begin_src authinfo +machine api.github.com login yourlogin^code-review password MYTOKENGOESHERE +#+end_src + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/tools/make/README.org b/modules/tools/make/README.org new file mode 100644 index 000000000..20c54d741 --- /dev/null +++ b/modules/tools/make/README.org @@ -0,0 +1,54 @@ +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/pass/README.org b/modules/tools/pass/README.org index f1d60e613..553fdc1e1 100644 --- a/modules/tools/pass/README.org +++ b/modules/tools/pass/README.org @@ -1,55 +1,65 @@ -#+TITLE: tools/pass -#+DATE: May 4, 2020 -#+SINCE: V2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/pdf/README.org b/modules/tools/pdf/README.org index 48b6959f1..ddf07aa72 100644 --- a/modules/tools/pdf/README.org +++ b/modules/tools/pdf/README.org @@ -1,55 +1,55 @@ -#+TITLE: tools/pdf -#+DATE: February 6, 2018 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+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 +57,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 +88,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 +99,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 diff --git a/modules/tools/prodigy/README.org b/modules/tools/prodigy/README.org new file mode 100644 index 000000000..d60b39544 --- /dev/null +++ b/modules/tools/prodigy/README.org @@ -0,0 +1,51 @@ +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/rgb/README.org b/modules/tools/rgb/README.org index d05dfaf2f..62cde165a 100644 --- a/modules/tools/rgb/README.org +++ b/modules/tools/rgb/README.org @@ -1,35 +1,36 @@ -#+TITLE: tools/rgb -#+DATE: May 6, 2020 -#+SINCE: 3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+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 +40,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 diff --git a/modules/tools/taskrunner/README.org b/modules/tools/taskrunner/README.org index b37a9bdba..2fe21ccf5 100644 --- a/modules/tools/taskrunner/README.org +++ b/modules/tools/taskrunner/README.org @@ -1,38 +1,62 @@ -#+TITLE: tools/taskrunner -#+DATE: November 9, 2019 -#+SINCE: {replace with next tagged release version} -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/terraform/README.org b/modules/tools/terraform/README.org index 16eb3d7cd..2956cbedc 100644 --- a/modules/tools/terraform/README.org +++ b/modules/tools/terraform/README.org @@ -1,69 +1,80 @@ -#+TITLE: tools/terraform -#+DATE: November 21, 2019 -#+SINCE: v2.1.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+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). +[[doom-module:][:tools terraform]] provides commands under [[kbd:][]] to run the most common +Terraform operations: +| key | description | +|-----------------+--------------------------| +| [[kbd:][ i]] | Runs ~$ terraform init~ | +| [[kbd:][ p]] | Runs ~$ terraform plan~ | +| [[kbd:][ a]] | Runs ~$ terraform apply~ | -* Appendix -** Keybindings -*** :localleader -| key | description | -|-----+-----------------------| -| =i= | Run =terraform init= | -| =p= | Run =terraform plan= | -| =a= | Run =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 diff --git a/modules/tools/tmux/README.org b/modules/tools/tmux/README.org new file mode 100644 index 000000000..3df420341 --- /dev/null +++ b/modules/tools/tmux/README.org @@ -0,0 +1,50 @@ +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/tools/upload/README.org b/modules/tools/upload/README.org index 45016e341..274ed8fcf 100644 --- a/modules/tools/upload/README.org +++ b/modules/tools/upload/README.org @@ -1,64 +1,80 @@ -#+TITLE: tools/upload -#+DATE: Feb 19, 2020 -#+SINCE: 2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+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 diff --git a/modules/ui/README.org b/modules/ui/README.org new file mode 100644 index 000000000..986e54575 --- /dev/null +++ b/modules/ui/README.org @@ -0,0 +1,11 @@ +# -*- mode: doom-docs-org -*- +#+title: :ui +#+created: July 29, 2021 +#+since: 21.12.0 + +* Description +For modules concerned with changing Emacs' appearance or providing interfaces +for its features, like sidebars, tabs, or fonts. + +* Frequently asked questions +/This category has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] diff --git a/modules/ui/deft/README.org b/modules/ui/deft/README.org index 4600960a3..7bacc8719 100644 --- a/modules/ui/deft/README.org +++ b/modules/ui/deft/README.org @@ -1,51 +1,76 @@ -#+TITLE: ui/deft -#+DATE: August 27, 2018 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui deft +#+subtitle: Notational velocity for Emacs +#+created: August 26, 2018 +#+since: 21.12.0 (#835) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -[[https://jblevins.org/projects/deft/][Deft]] is a major mode for creating, browsing, and filtering notes written in plain text formats, such as org-mode, markdown, and LaTeX. It enables you to quickly jot down thoughts and easily retrieve them later. +* Description :unfold: +[[https://jblevins.org/projects/deft/][Deft]] is a major mode for creating, browsing, and filtering notes written in +plain text formats, such as org-mode, markdown, and LaTeX. It enables you to +quickly jot down thoughts and easily retrieve them later. ** 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/jrblevin/deft][deft]] +** Packages +- [[doom-package:][deft]] -* Prerequisites -This module has no prerequisites. +** Hacks +/No hacks documented for this module./ -* Configuration -To use deft, you first need to specify the directory in which your notes are stored: +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -#+begin_src elisp -;; ~/.doom.d/config.el +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +To use deft, you first need to specify the directory in which your notes are +stored: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq deft-directory "~/notes") #+end_src The default note format is org-mode. You can change this by setting the value of -the variable ~deft-default-extension~. Replacing the value with ~"md"~, for example, -will change the default note format to markdown: - -#+begin_src elisp -(setq deft-default-extension "md") +the variable ~deft-default-extension~. Replacing the value with ~"md"~, for +example, will change the default note format to markdown: +#+begin_src emacs-lisp +(after! deft + (setq deft-default-extension "md")) #+end_src -You may also want to alter the way titles and file names are automatically created by editing ~deft-use-filename-as-title~ and/or ~deft-use-filter-string-for-filename~. +You may also want to alter the way titles and file names are automatically +created by editing ~deft-use-filename-as-title~ and/or +~deft-use-filter-string-for-filename~. -Further customization options can be found here: https://github.com/jrblevin/deft#other-customizations +Further customization options can be found here: +https://github.com/jrblevin/deft#other-customizations * Troubleshooting -It is [[https://github.com/hlissner/doom-emacs/pull/2845/commits/dce80a3c8032f5390f4e763e18a108d5f3f08772][not recommended]] to re-enable deft's buffer auto-save. +[[doom-report:][Report an issue?]] + +- It is [[https://github.com/hlissner/doom-emacs/pull/2845/commits/dce80a3c8032f5390f4e763e18a108d5f3f08772][not recommended]] to re-enable deft's buffer auto-save. + +* 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 diff --git a/modules/ui/doom-dashboard/README.org b/modules/ui/doom-dashboard/README.org index 7120ea470..3f7547e82 100644 --- a/modules/ui/doom-dashboard/README.org +++ b/modules/ui/doom-dashboard/README.org @@ -1,18 +1,10 @@ -#+TITLE: ui/doom-dashboard -#+DATE: October 9, 2019 -#+SINCE: v1.3 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui doom-dashboard +#+subtitle: Welcome to your doom +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] - - [[#a-custom-banner][A custom banner]] - - [[#adding-text-to-the-dashboard][Adding text to the dashboard]] - - [[#customizing-faces][Customizing Faces]] - -* Description +* Description :unfold: This module adds a minimalistic, Atom-inspired dashboard to Emacs. Besides eye candy, the dashboard serves two other purposes: @@ -29,28 +21,53 @@ Besides eye candy, the dashboard serves two other purposes: of the last open buffer, ~M-x find-file~ will work from the directory I expect. -** Module Flags -This module provides no flags. +** Maintainers +- [[doom-user:][@hlissner]] -* Prerequisites -This module only requires that ~all-the-icons~'s icon fonts are installed. +[[doom-contrib-maintainer:][Become a maintainer?]] -It should've been installed when you first installed Doom, but ~M-x -all-the-icons-install-fonts~ will install them again. +** 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 only requires that ~all-the-icons~'s icon fonts are installed, which +should've been installed when you ran ~$ doom install~. Otherwise, use ~M-x +all-the-icons-install-fonts~ to install them. + +* Usage +Once this module is enabled, the dashboard will present itself after opening a +fresh instance of Emacs, or after killing all real buffers. + +You can forcibly open the dashboard with ~M-x +doom-dashboard/open~. + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** A custom banner To use a custom image as your banner, change ~fancy-splash-image~: - -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (setq fancy-splash-image "~/my/banners/image.png") -#+END_SRC +#+end_src #+begin_quote -Doom will fall back to its ASCII banner in Terminal Emacs. To replace the ASCII -banner, replace the ~doom-dashboard-widget-banner~ function in -~+doom-dashboard-functions~ with a function that inserts your new banner into -the current file. + πŸ“Œ Doom will fall back to its ASCII banner in Terminal Emacs. To replace the + ASCII banner, replace the ~doom-dashboard-widget-banner~ function in + ~+doom-dashboard-functions~ with a function that inserts your new banner + into the current file. #+end_quote ** Adding text to the dashboard @@ -59,15 +76,16 @@ redraw. Add your own functions to operate on the buffer and potentially add whatever you like to Doom's splash screen. #+begin_quote -Keep in mind that inserting text from expensive sources, e.g. your org agenda, -will negate most of Doom's startup benefits. + 🚧 Keep in mind that inserting text from expensive sources, e.g. your org + agenda, will negate most of Doom's startup benefits. #+end_quote ** Customizing Faces -Doom's dashboard defaults to inheriting faces set by the current theme. If you wish -to customize it independently of the theme (or just inherit a different color -from the theme) you can make use of ~custom-set-faces!~ or ~custom-theme-set-faces!~ -#+BEGIN_SRC elisp +Doom's dashboard defaults to inheriting faces set by the current theme. If you +wish to customize it independently of the theme (or just inherit a different +color from the theme) you can make use of ~custom-set-faces!~ or +~custom-theme-set-faces!~: +#+begin_src emacs-lisp (custom-set-faces! '(doom-dashboard-banner :foreground "red" :background "#000000" :weight bold) '(doom-dashboard-footer :inherit font-lock-constant-face) @@ -75,9 +93,10 @@ from the theme) you can make use of ~custom-set-faces!~ or ~custom-theme-set-fa '(doom-dashboard-loaded :inherit font-lock-warning-face) '(doom-dashboard-menu-desc :inherit font-lock-string-face) '(doom-dashboard-menu-title :inherit font-lock-function-name-face)) -#+END_SRC +#+end_src + or for a per-theme setting -#+BEGIN_SRC elisp +#+begin_src emacs-lisp (custom-theme-set-faces! 'doom-tomorrow-night '(doom-dashboard-banner :foreground "red" :background "#000000" :weight bold) '(doom-dashboard-footer :inherit font-lock-constant-face) @@ -85,4 +104,15 @@ or for a per-theme setting '(doom-dashboard-loaded :inherit font-lock-warning-face) '(doom-dashboard-menu-desc :inherit font-lock-string-face) '(doom-dashboard-menu-title :inherit font-lock-function-name-face)) -#+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 diff --git a/modules/ui/doom-dashboard/config.el b/modules/ui/doom-dashboard/config.el index 254062ce2..1e3c17137 100644 --- a/modules/ui/doom-dashboard/config.el +++ b/modules/ui/doom-dashboard/config.el @@ -172,7 +172,7 @@ PLIST can have the following properties: ;;; Major mode (define-derived-mode +doom-dashboard-mode special-mode - (format "DOOM v%s" doom-version) + (format "DOOM v%s" doom-core-version) "Major mode for the DOOM dashboard buffer." :syntax-table nil :abbrev-table nil @@ -512,7 +512,11 @@ What it is set to is controlled by `+doom-dashboard-pwd-policy'." (defun doom-dashboard-widget-footer () (insert - "\n" + (+doom-dashboard--center + +doom-dashboard--width + (propertize (concat "DOOM CORE: " doom-core-version " MODULES: " doom-version) + 'face 'font-lock-doc-face)) + "\n\n" (+doom-dashboard--center (- +doom-dashboard--width 2) (with-temp-buffer @@ -521,5 +525,6 @@ What it is set to is controlled by `+doom-dashboard-pwd-policy'." 'action (lambda (_) (browse-url "https://github.com/hlissner/doom-emacs")) 'follow-link t 'help-echo "Open Doom Emacs github page") + (buffer-string))) "\n")) diff --git a/modules/ui/doom-quit/README.org b/modules/ui/doom-quit/README.org index 03a93c174..08aec348b 100644 --- a/modules/ui/doom-quit/README.org +++ b/modules/ui/doom-quit/README.org @@ -1,39 +1,69 @@ -#+TITLE: ui/doom-quit -#+DATE: February 19, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui doom-quit +#+subtitle: One does not simply quit Emacs +#+created: February 19, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configurations][Configurations]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +A silly module that throws cute confirmation prompts at you when you exit Emacs, +like DOOM (the game) did. Some quotes are from the classic games, others are +random, nerdy references that no decent human being has any business +recognizing. + +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +/This module doesn't install any packages./ + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* Usage +Quit Emacs with [[kbd:][ q q]] and watch it go. The prompt only happens if you +have (real) buffers open. + +#+begin_quote + 🚧 This module won't kick in when killing daemon frames (because that isn't + actually β€œquitting” Emacs). +#+end_quote -* Description -A silly module that prompts you with messages when you try to quit, like DOOM -did. Some quotes are from Doom's quit-message list. Others are random, nerdy -references that no decent human being has any business recognising. -** Module Flags -This module provides no flags -** Plugins -This module uses no Plugins -* Prerequisites -This module provides no prerequisite -* Features -This module only works when you run individual Emacs instances and not the -daemon. * Configurations - you can configure the messages by adding to the variable ~+doom-quit-messages~ - #+BEGIN_SRC emacs-lisp -(setq +doom-quit-messages '(;;from doom 2 - "Don't go now, there's a dimensional shambler waiting at the dos prompt!" - "Get outta here and go back to your boring programs." - "If I were your boss, I'd deathmatch ya in a minute!" - "Look, bud. You leave now and you forfeit your body count!" - "You're lucky I don't smack you for thinking about leaving.")) - #+END_SRC +The messages presented by this module can be customized by changing the +~+doom-quit-messages~ variable: +#+begin_src emacs-lisp +(setq +doom-quit-messages + '(;;from doom 2 + "Don't go now, there's a dimensional shambler waiting at the dos prompt!" + "Get outta here and go back to your boring programs." + "If I were your boss, I'd deathmatch ya in a minute!" + "Look, bud. You leave now and you forfeit your body count!" + "You're lucky I don't smack you for thinking about leaving.")) + #+end_src + * Troubleshooting If you have any issues with this module do let me know + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* Appendix +** Variables +- [[var:][+doom-quit-messages]] + +** Functions +- [[fn:][+doom-quit-fn]] diff --git a/modules/ui/doom/README.org b/modules/ui/doom/README.org index 71ec163fa..80aa97ec7 100644 --- a/modules/ui/doom/README.org +++ b/modules/ui/doom/README.org @@ -1,93 +1,116 @@ -#+TITLE: ui/doom -#+DATE: October 9, 2019 -#+SINCE: v1.3 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui doom +#+subtitle: Make Doom fabulous again +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] - - [[#changing-theme][Changing theme]] - - [[#changing-fonts][Changing fonts]] -- [[#troubleshooting][Troubleshooting]] - - [[#strange-font-symbols][Strange font symbols]] - - [[#ugly-background-colors-in-tty-emacs-for-daemon-users][Ugly background colors in tty Emacs for daemon users]] +* Description :unfold: +This module gives Doom its signature look: powered by the [[doom-package:doom-themes][doom-one]] theme +(loosely inspired by [[https://github.com/atom/one-dark-syntax][Atom's One Dark theme]]) and [[doom-package:][solaire-mode]]. Includes: -* Description -This module gives Doom its signature look: powered by the =doom-one= theme -(inspired by Atom's One Dark theme) and =solaire-mode=. +- A custom folded-region indicator for [[doom-package:][hideshow]]. +- "Thin bar" fringe bitmaps for [[doom-package:][git-gutter-fringe]]. +- File-visiting buffers are slightly brighter (thanks to [[doom-package:][solaire-mode]]). -+ A colorscheme inspired by Atom's One Dark theme (now available in a separate - plugin: [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]]) -+ A custom folded-region indicator for ~hideshow~ -+ "Thin bar" fringe bitmaps for ~git-gutter-fringe~ -+ File-visiting buffers are slightly brighter (thanks to solaire-mode) +** Maintainers +- [[doom-user:][@hlissner]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/hlissner/emacs-doom-themes][doom-themes]] -+ [[https://github.com/hlissner/emacs-solaire-mode][solaire-mode]] +** Module flags +/This module has no flags./ -* Prerequisites -This module has no prerequisites. +** Packages +- [[doom-package:][doom-themes]] +- [[doom-package:][solaire-mode]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** Changing theme -Although this module uses the ~doom-one~ theme by default, [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]] offers a number of alternatives: +Although this module uses the ~doom-one~ theme by default, [[https://github.com/hlissner/emacs-doom-theme/][doom-themes]] offers a +number of alternatives: -+ *doom-one:* doom-themes' flagship theme, inspired by [[https://atom.io/][Atom's]] One Dark themes -+ *doom-vibrant:* a more vibrant version of doom-one -+ *doom-molokai:* based on Textmate's monokai -+ *doom-nova:* adapted from [[https://github.com/trevordmiller/nova-colors][Nova]] -+ *doom-one-light:* light version of doom-one -+ *doom-peacock:* based on Peacock from [[https://daylerees.github.io/][daylerees' themes]] -+ *doom-tomorrow-night:* by [[https://github.com/ChrisKempson/Tomorrow-Theme][Chris Kempson]] +- *doom-one:* doom-themes' flagship theme, inspired by [[https://atom.io/][Atom's]] One Dark themes +- *doom-vibrant:* a more vibrant version of doom-one +- *doom-molokai:* based on Textmate's monokai +- *doom-nova:* adapted from [[https://github.com/trevordmiller/nova-colors][Nova]] +- *doom-one-light:* light version of doom-one +- *doom-peacock:* based on Peacock from [[https://daylerees.github.io/][daylerees' themes]] +- *doom-tomorrow-night:* by [[https://github.com/ChrisKempson/Tomorrow-Theme][Chris Kempson]] +- And /many/ more... This can be changed by changing the ~doom-theme~ variable, e.g. - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq doom-theme 'doom-molokai) -#+END_SRC +#+end_src ** Changing fonts core/core-ui.el has four relevant variables: -+ ~doom-font~ :: the default font to use in Doom Emacs. -+ ~doom-big-font~ :: the font to use when ~doom-big-font-mode~ is enabled. -+ ~doom-variable-font~ :: the font to use when ~variable-pitch-mode~ is active (or where the ~variable-pitch~ face is used). -+ ~doom-unicode-font~ :: the font used to display unicode symbols. This is ignored if the =:ui unicode= module is enabled. +- ~doom-font~ :: the default font to use in Doom Emacs. +- ~doom-big-font~ :: the font to use when ~doom-big-font-mode~ is enabled. +- ~doom-variable-pitch-font~ :: the font to use when ~variable-pitch-mode~ is active + (or where the ~variable-pitch~ face is used). +- ~doom-unicode-font~ :: the font used to display unicode symbols. This is + ignored if the [[doom-module:][:ui unicode]] module is enabled. -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (setq doom-font (font-spec :family "Fira Mono" :size 12) doom-variable-pitch-font (font-spec :family "Fira Sans") doom-unicode-font (font-spec :family "DejaVu Sans Mono") doom-big-font (font-spec :family "Fira Mono" :size 19)) -#+END_SRC +#+end_src * Troubleshooting +[[doom-report:][Report an issue?]] + ** Strange font symbols If you're seeing strange unicode symbols, this is likely because you don't have ~all-the-icons~'s font icon installed. You can install them with ~M-x all-the-icons-install-fonts~. ** Ugly background colors in tty Emacs for daemon users -=solaire-mode= is an aesthetic plugin that makes non-file-visiting buffers -darker than the rest of the Emacs' frame (to visually differentiate temporary -windows or sidebars from editing windows). This looks great in GUI Emacs, but -can look questionable in the terminal. +[[doom-package:][solaire-mode]] is an aesthetic plugin that makes non-file-visiting buffers darker +than the rest of the Emacs' frame (to visually differentiate temporary windows +or sidebars from editing windows). This looks great in GUI Emacs, but can look +questionable in the terminal. -It disables itself if you start tty Emacs with ~emacs -nw~, but if you create a -tty frame from a daemon (which solaire-mode cannot anticipate), you'll get an +It disables itself if you start tty Emacs with ~$ emacs -nw~, but if you create +a tty frame from a daemon (which solaire-mode cannot anticipate), you'll get an ugly background instead. If you only use Emacs in the terminal, your best bet is to disable the solaire-mode package: - -#+BEGIN_SRC elisp -;; in ~/.doom.d/packages.el +#+begin_src emacs-lisp +;; in $DOOMDIR/packages.el (package! solaire-mode :disable t) -#+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 diff --git a/modules/ui/emoji/README.org b/modules/ui/emoji/README.org index 17045fe58..860d9860c 100644 --- a/modules/ui/emoji/README.org +++ b/modules/ui/emoji/README.org @@ -1,40 +1,40 @@ -#+TITLE: ui/emoji -#+DATE: September 30, 2020 -#+SINCE: v3.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui emoji +#+subtitle: πŸ’© +#+created: September 30, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - -* Description -Displays and inserts emojis (ASCII, Github style, unicode). - -+ Converts recognized text to emojis. -+ Enables inserting emojis. +* Description :unfold: +This module gives Emacs the ability to display and insert emojis (ASCII, Github +style, or unicode styles), as well as convert certain text patterns (e.g. +=:smile:=) into emojis. ** Maintainers -This module has no dedicated maintainers. +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+ascii= Include plain text emojis like =:)=. -+ =+github= Include Github-style emojis like =:smile:=. -+ =+unicode= Include unicode emojis like πŸ™‚. +** Module flags +- +ascii :: + Include plain text emojis like =:)=. +- +github :: + Include Github-style emojis like =:smile:=. +- +unicode :: + Include unicode emojis like πŸ™‚. -** Plugins -+ [[https://github.com/iqbalansari/emacs-emojify][emojify]] by @iqbalansari +** Packages +- [[doom-package:][emojify]] -* Prerequisites +** Hacks +/No hacks documented for this module./ -See the [[https://github.com/iqbalansari/emacs-emojify/blob/master/README.org#requirements][emojify requirements]] docs: +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -#+BEGIN_QUOTE +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +From the [[https://github.com/iqbalansari/emacs-emojify/blob/master/README.org#requirements][emojify requirements]] docs: +#+begin_quote The [[https://github.com/iqbalansari/emacs-emojify][emojify]] package requires Emacs *v24.3* and above. Emacs should be compiled with support for *PNG* images to display emojis as images. It is *recommended* that Emacs is compiled with *ImageMagick* support. ~emojify~ will use it to @@ -44,13 +44,25 @@ color for emojis to workaround the bug described in [[https://github.com/iqbalan PNG support might require some additional steps to on Windows, you might find [[http://stackoverflow.com/questions/2650041/emacs-under-windows-and-png-files][this]] stackoverflow answer helpful. -#+END_QUOTE +#+end_quote -* 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 diff --git a/modules/ui/hl-todo/README.org b/modules/ui/hl-todo/README.org index 8f8d5e090..d7b58c2cf 100644 --- a/modules/ui/hl-todo/README.org +++ b/modules/ui/hl-todo/README.org @@ -1,83 +1,88 @@ -#+TITLE: :ui hl-todo -#+DATE: February 19, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui hl-todo +#+subtitle: TODO FIXME NOTE DEPRECATED HACK REVIEW +#+created: February 19, 2017 +#+since: 1.3 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#making-items][Making Items]] - - [[#keybindings][Keybindings]] - - [[#adding-items][Adding items.]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +This module adds syntax highlighting for various tags in code comments, such as +=TODO=, =FIXME=, and =NOTE=, among others. -* Description -This module adds syntax highlighting for TODO/FIXME/NOTE tags in programming -major-modes. +** Maintainers +- [[doom-user:][@hlissner]] -** Module Flags -This module provides no flags +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/tarsius/hl-todo][hl-todo]] +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][hl-todo]] -* Prerequisites -This module has no prerequisites +** 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./ -** Making Items -You can make a TODO item by simply writing -+ =TODO= - For things that need to be done, just not today. -+ =HACK= - For tidbits that are unconventional and not intended uses of the +* 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 + +By enabling this module, the following keywords will be highlighted if they +occur in code comments: + +- =TODO=: For things that need to be done, just not today. +- =HACK=: For tidbits that are unconventional and not intended uses of the constituent parts, and may break in a future update. -+ =FIXME= - For problems that will become bigger problems later if not fixed ASAP. -+ =REVIEW= - for things that were done hastily and/or hasn't been thoroughly +- =FIXME=: For problems that will become bigger problems later if not fixed + ASAP. +- =REVIEW=: for things that were done hastily and/or hasn't been thoroughly tested. it may not even be necessary! -+ =NOTE= - For especially important gotchas with a given implementation, - directed at another user other than the author. -+ =DEPRECATED= - For things that just gotta go and will soon be gone. -+ =BUG= - For a known bug that needs a workaround -+ =XXX= - For warning about a problematic or misguiding code +- =NOTE=: For especially important gotchas with a given implementation, directed + at another user other than the author. +- =DEPRECATED=: For things that just gotta go and will soon be gone. +- =BUG=: For a known bug that needs a workaround. +- =XXX=: For warning about a problematic or misguiding code. ** Keybindings -| keybind | description | -|-----------+----------------------------------| -| =]t= | go to next TODO item | -| =[t= | go to previous TODO item | -| =SPC p t= | show all TODO items in a project | -| =SPC s p= | search project for a string | -| =SPC s b= | search buffer for string | +| keybind | description | +|---------+----------------------------------| +| [[kbd:][]t]] | go to next TODO item | +| [[kbd:][[t]] | go to previous TODO item | +| [[kbd:][SPC p t]] | show all TODO items in a project | +| [[kbd:][SPC s p]] | search project for a string | +| [[kbd:][SPC s b]] | search buffer for string | -** TODO Adding items. -The way you would add a TODO item is to use a snippet but these have not been -made. you can make them yourself by adding the snippet to -=$DOOMDIR/snippets/MAJOR-MODE/name-of-snippet=. you will find more info on how -to make them [[https://github.com/hlissner/doom-snippets][here]] +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration To add your own ITEMS you would need to configure them using -~hl-todo-keyword-faces~ -#+BEGIN_SRC emacs-lisp -;; the default +~hl-todo-keyword-faces~: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (after! hl-todo (setq hl-todo-keyword-faces - `( - ("FOO" . ,(face-foreground "MY COLOUR HEX CODE")) + `(("FOO" . ,(face-foreground "MY COLOUR HEX CODE")) ("BAR" . ,(face-foreground 'my-colour-var))))) -#+END_SRC +#+end_src -* TODO Troubleshooting -If you have any problems with this module do get in touch! +* 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 diff --git a/modules/ui/hydra/README.org b/modules/ui/hydra/README.org index 3100b0955..2713501fa 100644 --- a/modules/ui/hydra/README.org +++ b/modules/ui/hydra/README.org @@ -1,31 +1,63 @@ -#+TITLE: ui/hydra -#+DATE: october 29, 2019 -#+SINCE: 2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui hydra +#+subtitle: Discount modality for mythological beast hunters +#+created: October 29, 2019 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] +#+begin_quote + 🚧 *This module is deprecated.* The module is too trivially small, and it's + always been unclear how hydra fits into Doom's vision for its UI. It's been + decided that Doom will head toward Embark, transient, or hercules instead. +#+end_quote -* Description +* Description :unfold: This module adds hydra to Doom Emacs, as well as a few custom built hydras to -start with : +start with: -+ A hydra to control windows ~+hydra/window-nav/body~ -+ A hydra to control text zoom level ~+hydra/text-zoom/body~ +- A hydra to control windows ~+hydra/window-nav/body~. +- A hydra to control text zoom level ~+hydra/text-zoom/body~. -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/abo-abo/hydra][hydra]] +** Module flags +/This module has no flags./ -* Prerequisites -This module has no prerequisites. +** Packages +- [[doom-package:][hydra]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration Configuring this module is only setting bindings to the provided hydra, or -creating your own ones ! +creating your own ones! + +* 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 diff --git a/modules/ui/indent-guides/README.org b/modules/ui/indent-guides/README.org new file mode 100644 index 000000000..10f96010f --- /dev/null +++ b/modules/ui/indent-guides/README.org @@ -0,0 +1,50 @@ +# -*- mode: doom-docs-org -*- +#+title: :ui indent-guides +#+subtitle: Line up them indent columns +#+created: March 11, 2019 +#+since: 21.12.0 + +* TODO Description :unfold: +/(No description yet)/ + +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][highlight-indent-guides]] + +** 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 diff --git a/modules/ui/ligatures/README.org b/modules/ui/ligatures/README.org index 66d969ff1..3b5a997de 100644 --- a/modules/ui/ligatures/README.org +++ b/modules/ui/ligatures/README.org @@ -1,72 +1,68 @@ -#+TITLE: ui/ligatures -#+DATE: June 16, 2018 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui ligatures +#+subtitle: Distract folks from your code +#+created: June 16, 2018 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#font-ligatures-module-flags][Font ligatures module flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] - - [[#mutsuharus-emacs-mac-port-or-emacs-28-with-harfbuzz-support][Mutsuharu's emacs-mac port or Emacs 28+ with Harfbuzz support]] - - [[#not-emacs-mac-and-emacs--27][Not Emacs-mac and Emacs <= 27]] -- [[#features][Features]] - - [[#mathematical-symbols-replacement][Mathematical symbols replacement]] - - [[#coding-ligatures][Coding ligatures]] -- [[#configuration][Configuration]] - - [[#setting-ligatures][Setting ligatures]] - - [[#changing-ligatures][Changing ligatures]] -- [[#troubleshooting][Troubleshooting]] - -* Description +* Description :unfold: This module enables ligatures and arbitrary symbol substitutions with ~mac-auto-operator-composition-mode~ (on supported macOS systems) or composition tables (harfbuzz on Emacs 28), falling back on ~prettify-symbols-mode~ otherwise. ** Maintainers -This module has no dedicated maintainers. +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -+ =+extra= Enables extra symbol substitutions in certain modes, for example - ~lambda~ in lisps are replaced with ~Ξ»~. - -*** Font ligatures module flags -This module provides four flags for enabling fall-back ligature support for a -particular font. They are: - -+ =+fira= Enables =Fira Code= ligatures. This requires Fira Code Symbol and a - patched version of Fira Code (see below). -+ =+hasklig= Enable =Hasklig= ligatures. This requires a patched version of the - HaskLig font (see below). -+ =+iosevka= Enable =Iosevka= ligatures. This requires a patched version of the - Iosevka font (see below). -+ =+pragmata-pro= Enable =Pragmata Pro= ligatures. This requires the [[https://www.fsd.it/shop/fonts/pragmatapro/][Pragmata - Pro font]]. +** Module flags +- +extra :: + Enables extra symbol substitutions in certain modes, for example ~lambda~ in + lisps are replaced with ~Ξ»~. +- +fira :: + Enable =Fira Code= ligatures. This requires Fira Code Symbol and [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched + version of Fira Code]]. +- +hasklig :: + Enable =Hasklig= ligatures. This requires [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched version of the HaskLig + font]]. +- +iosevka :: + Enable =Iosevka= ligatures. This requires [[id:a7e7402b-e202-4860-878b-d1933cff1d16][a patched version of the Iosevka + font]]. +- +pragmata-pro :: + Enable =Pragmata Pro= ligatures. This requires the [[https://www.fsd.it/shop/fonts/pragmatapro/][Pragmata Pro font]]. #+begin_quote -All these flags are ignored _if_ you're sporting either a) Emacs 28+ with -Harfbuzz support (which can compose ligatures natively), or b) Mitsuharu's -=emacs-mac= build on macOS (which uses ~mac-auto-operator-composition-mode~). + 🚧 Font flags are ignored _if_ you're sporting either a) Emacs 28+ with + Harfbuzz support (which can compose ligatures natively), or b) Mitsuharu's + =emacs-mac= build on macOS (which uses + ~mac-auto-operator-composition-mode~). #+end_quote -** Plugins -This module installs no packages. +** 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.]] -* Prerequisites This module requires one of three setups for ligatures to work: - A recent enough version of Emacs which will compose ligatures automatically (Emacs 28 with Harfbuzz support), or -- Mitsuharu's =emacs-mac= build on macOS (available on homebrew), or +- Mitsuharu's =emacs-mac= build on macOS (available on Homebrew), or - A patched font for Doom's fallback ligature support. ** Mutsuharu's emacs-mac port or Emacs 28+ with Harfbuzz support Ligatures should be handled without any additional configuration. ** Not Emacs-mac and Emacs <= 27 +:PROPERTIES: +:ID: a7e7402b-e202-4860-878b-d1933cff1d16 +:END: 1. Enable one of the four ligature font flags: =+fira=, =+hasklig=, =+iosevka= or =+pragmata-pro=. 2. Install the patched version of the associated font with ~M-x @@ -74,8 +70,13 @@ Ligatures should be handled without any additional configuration. way because it is a non-free font and must be purchased and installed manually. -* TODO Features +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + ** TODO Mathematical symbols replacement + ** Coding ligatures This module includes configuration to compose combinations like =->= or =::= into prettier glyphs (called a ligature). Depending on the current version of @@ -85,8 +86,8 @@ emacs, this is implemented in two different ways : which haves the ligatures as separate unicode symbols, and using prettify-symbols-mode, =->=-like combinations are manually listed and replaced with the correct symbol. The mapping between =->=-like sequences and unicode - values in the font are font-specific ; therefore =+fira=, =+iosevka=... files - and specific fonts are necessary for it to work. + values in the font are font-specific ; therefore [[doom-module:][+fira]], [[doom-module:][+iosevka]]... files and + specific fonts are necessary for it to work. - composition-function-table method :: regexps are used to match all the usual sequences which are composed into ligatures. These regexps are passed to emacs directly, which asks Harfbuzz to shape it. Ligatures are obtained @@ -102,17 +103,23 @@ Even though harfbuzz has been included in emacs 27, there is currently a [[https (#40864)]] which prevents a safe usage of /composition-function-table/ method in emacs 27. -* Configuration +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + ** Setting ligatures If you want to set ligatures for modules that don't have them by default you can -use the ~set-ligatures!~ macro in your config el file -#+BEGIN_SRC emacs-lisp +use the ~set-ligatures!~ macro: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (after! PACKAGE (set-ligatures! 'MAJOR-MODE :symbol "keyword")) -#+END_SRC -eg. -#+BEGIN_SRC emacs-lisp +#+end_src + +E.g. +#+begin_src emacs-lisp (after! go-mode ; in this case the major mode and package named the same thing (set-ligatures! 'go-mode :def "func" ; function keyword @@ -123,9 +130,10 @@ eg. :float "float" :bool "bool" :for "for" :return "return" :yeild "yeild")) -#+END_SRC -you can set these symbols out of the box -#+BEGIN_SRC emacs-lisp +#+end_src + +You can set these symbols out of the box: +#+begin_src emacs-lisp (set-ligatures! 'MAJOR-MODE ;; Functional :lambda "lambda keyword" @@ -158,19 +166,18 @@ you can set these symbols out of the box :tuple "Tuple Keyword " :pipe "Pipe Keyword" ;; FIXME: find a non-private char :dot "Dot operator") -#+END_SRC +#+end_src -If you have multiple versions of the same keyword you can set the symbol twice - -#+BEGIN_SRC emacs-lisp +If you have multiple versions of the same keyword you can set the symbol twice: +#+begin_src emacs-lisp (set-ligatures! scala-mode :null "none" :null "None") -#+END_SRC -** Changing ligatures -if you don't like the symbols chosen you can change them by using... +#+end_src -#+BEGIN_SRC emacs-lisp +** Changing ligatures +if you don't like the symbols chosen you can change them by using: +#+begin_src emacs-lisp ;; you don't need to include all of them you can pick and mix (plist-put! +ligatures-extra-symbols ;; org @@ -210,7 +217,23 @@ if you don't like the symbols chosen you can change them by using... :tuple "⨂" :pipe "ξ„΅" ;; FIXME: find a non-private char :dot "β€’") ;; you could also add your own if you want -#+END_SRC +#+end_src -* TODO Troubleshooting - If you have any problems with this module, do get in touch! +* Troubleshooting +[[doom-report:][Report an issue?]] + +** Some symbols are not rendering correctly +This can usually be fixed by doing one of the following: + +- Make sure Symbola (the font) is installed on your system. +- Otherwise, change [[var:][doom-unicode-font]] (set to Symbola by default). +- Disable the [[doom-module:][:ui unicode]] module. It not only overrides [[var:][doom-unicode-font]], but + should only be used as a last resort. + +* 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 diff --git a/modules/ui/minimap/README.org b/modules/ui/minimap/README.org index 28d485899..37defff40 100644 --- a/modules/ui/minimap/README.org +++ b/modules/ui/minimap/README.org @@ -1,43 +1,60 @@ -#+TITLE: :ui minimap -#+DATE: May 8, 2020 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui minimap +#+subtitle: A map for lost programmers +#+created: May 08, 2020 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] - - [[#scrolling-is-slowlaggy][Scrolling is slow/laggy]] - - [[#minimap-doesnt-close-when-disabled][Minimap doesn't close when disabled]] - -* Description -This module adds a minimap to the right side of Emacs, similar to the feature -found in many other editors. +* Description :unfold: +This module displays a minimap of the buffer in a sidebar, similar to the +feature found in many other editors. ** Maintainers -+ [[https://github.com/rushsteve1][@rushsteve1]] (Author) +- [[doom-user:][@rushsteve1]] -** Module Flags -This module provides no flags. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://elpa.gnu.org/packages/minimap.html][minimap.el]] +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][minimap]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features A minimap which provides an overview of the current buffer to the side, displaying the currently visible region and the current line. You can left-click and drag to scroll along the buffer, or right-click anywhere to jump to there. -* Configuration +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + There are a number of options provided by the =minimap.el= package this module -is based on. The easiest way to see all of them is =SPC h v minimap=. +is based on. The easiest way to see all of them is [[kbd:][SPC h v minimap]]. * Troubleshooting +[[doom-report:][Report an issue?]] + ** Scrolling is slow/laggy -Disable the minimap using =SPC t m= +Disable the minimap using [[kbd:][SPC t m]]. ** TODO Minimap doesn't close when disabled + +* 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 diff --git a/modules/ui/modeline/README.org b/modules/ui/modeline/README.org index 50886922b..980946e85 100644 --- a/modules/ui/modeline/README.org +++ b/modules/ui/modeline/README.org @@ -1,53 +1,61 @@ -#+TITLE: ui/modeline -#+DATE: July 29, 2018 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui modeline +#+subtitle: Snazzy, Atom-inspired modeline, plus API +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_2:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#usage][Usage]] - - [[#hiding-the-modeline][Hiding the modeline]] - - [[#switching-the-modeline-and-header-line][Switching the modeline and header line]] -- [[#configuration][Configuration]] - - [[#changing-the-default-modeline][Changing the default modeline]] - - [[#activating-a-format][Activating a format]] - - [[#defining-a-modeline-format][Defining a modeline format]] - - [[#defining-a-modeline-segment][Defining a modeline segment]] - - [[#extracting-dooms-modeline-into-your-config][Extracting Doom's modeline into your config]] -- [[#troubleshooting][Troubleshooting]] - - [[#where-are-my-minor-modes][Where are my minor modes?]] - - [[#icons-in-my-modeline-look-strange][Icons in my modeline look strange]] - - [[#the-right-side-of-the-modeline-is-cut-off][The right side of the modeline is cut off]] -- [[#appendix][Appendix]] - - [[#autodefs][Autodefs]] - - [[#variables][Variables]] - - [[#faces][Faces]] - -* Description +* Description :unfold: This module provides an Atom-inspired, minimalistic modeline for Doom Emacs, -powered by [[https://github.com/seagle0128/doom-modeline][the doom-modeline package]] (where you can find screenshots). +powered by the [[doom-package:][doom-modeline]] package (where you can find screenshots). -** Module Flags -+ =+light= Enables a lighter, less featureful version of the modeline that does - not depend on ~doom-modeline~, which has performances issues in some cases. +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ [[https://github.com/seagle0128/doom-modeline][doom-modeline]] -+ [[https://github.com/syohex/emacs-anzu][anzu]] -+ [[https://github.com/syohex/emacs-evil-anzu][evil-anzu]] +[[doom-contrib-maintainer:][Become a maintainer?]] -* Prerequisites -This module has no prerequisites. +** Module flags +- +light :: + Enable a lighter, less featureful version of the modeline that does not depend + on [[doom-package:][doom-modeline]], which has performances issues in some cases. -* Usage -** TODO Hiding the modeline +** Packages +- [[doom-package:][anzu]] +- [[doom-package:][doom-modeline]] unless [[doom-module:][+light]] +- [[doom-package:][evil-anzu]] if [[doom-module:][:editor evil]] + +** 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 + +** Hiding the modeline +- You can use ~M-x hide-mode-line-mode RET~ to hide modeline for the current + buffer. +- Also, there is ~global-hide-mode-line-mode~ for globally hiding modeline. You + can just add =(global-hide-mode-line-mode)= into =~/.doom.d/config.el~. +- ~hide-mode-line-excluded-modes~ can be set for preventing + ~global-hide-mode-line-mode~ hiding modeline for buffers with the + corresponding major modes. ** TODO Switching the modeline and header line -* Configuration +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + ** TODO Changing the default modeline ** TODO Activating a format @@ -59,20 +67,40 @@ This module has no prerequisites. ** TODO Extracting Doom's modeline into your config * Troubleshooting +[[doom-report:][Report an issue?]] + ** Where are my minor modes? I rarely need to know what minor modes are active, so I removed them. ~M-x doom/describe-active-minor-mode~ was written to substitute for it. -** TODO Icons in my modeline look strange -** TODO The right side of the modeline is cut off -I believe the consensus is: this is due to oversized icons, i.e. a font issue. Some possible solutions: +** Icons in my modeline look strange +1. Check whether ~all-the-icons~ are installed. Run ~M-x + all-the-icons-install-fonts~ to install the resource fonts. Note that + ~all-the-icons~ only support GUI. See [[https://github.com/domtronn/all-the-icons.el][all-the-icons]] for details. + +2. ~cnfonts~ will conflict with ~all-the-icons~. You can refer the following + workaround: + #+begin_src emacs-lisp + ;; See https://github.com/seagle0128/doom-modeline/issues/278#issuecomment-569510336 + ;; Add to $DOOMDIR/packages.el + (package! cnfonts) + ;; Add to $DOOMDIR/config.el + (add-hook 'after-setting-font-hook #'cnfonts-set-font) + #+end_src + +3. If ~all-the-icons~ fonts are installed while the icons cannot display + correctly, please install the non-free font [[https://dn-works.com/wp-content/uploads/2020/UFAS-Fonts/Symbola.zip][Symbola]]. This issue usually + occurs on Windows. + +** The right side of the modeline is cut off +I believe the consensus is: this is due to oversized icons, i.e. a font issue. +Some possible solutions: 1. Tweak ~all-the-icons-scale-factor~ (1.2 by default): ~(setq all-the-icons-scale-factor 1.1)~ 2. Add some padding to the modeline definition: - - #+begin_src elisp + #+begin_src emacs-lisp (after! doom-modeline (doom-modeline-def-modeline 'main '(bar matches buffer-info remote-host buffer-position parrot selection-info) @@ -80,18 +108,16 @@ I believe the consensus is: this is due to oversized icons, i.e. a font issue. S #+end_src 3. Use another font for the mode line (or a different ~:height~) (source) - - #+BEGIN_SRC elisp + #+begin_src emacs-lisp (custom-set-faces! '(mode-line :family "Noto Sans" :height 0.9) '(mode-line-inactive :family "Noto Sans" :height 0.9)) - #+END_SRC + #+end_src -(Mentioned in #1680, #278 and seagle0128/doom-modeline#334) +(Mentioned in [[doom-ref:][#1680]], [[doom-ref:][#278]] and [[https://github.com/seagle0128/doom-modeline/issues/334][seagle0128/doom-modeline#334]]) 4. Change the width of icon characters in ~char-width-table~: - - #+BEGIN_SRC elisp + #+begin_src emacs-lisp (add-hook! 'doom-modeline-mode-hook (let ((char-table char-width-table)) (while (setq char-table (char-table-parent char-table))) @@ -104,62 +130,72 @@ I believe the consensus is: this is due to oversized icons, i.e. a font issue. S (optimize-char-table table) (set-char-table-parent table char-table) (setq char-width-table table))))) - #+END_SRC + #+end_src - If this doesn't help, try different values for ~width~ such as ~width 1~ or ~width 3~. + If this doesn't help, try different values for ~width~ such as ~width 1~ or + ~width 3~. + +* 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 ** Autodefs -+ ~def-modeline-format! NAME LEFT &optional RIGHT~ -+ ~def-modeline-segment! NAME &rest REST~ -+ ~set-modeline! NAME &optional DEFAULT~ +- ~def-modeline-format! NAME LEFT &optional RIGHT~ +- ~def-modeline-segment! NAME &rest REST~ +- ~set-modeline! NAME &optional DEFAULT~ + ** Variables -+ doom-modeline-height -+ doom-modeline-bar-width -+ doom-modeline-buffer-file-name-style -+ doom-modeline-icon -+ doom-modeline-major-mode-icon -+ doom-modeline-major-mode-color-icon -+ doom-modeline-buffer-state-icon -+ doom-modeline-buffer-modification-icon -+ doom-modeline-minor-modes -+ doom-modeline-enable-word-count -+ doom-modeline-buffer-encoding -+ doom-modeline-indent-info -+ doom-modeline-checker-simple-format -+ doom-modeline-vcs-max-length -+ doom-modeline-persp-name -+ doom-modeline-lsp -+ doom-modeline-github -+ doom-modeline-github-interval -+ doom-modeline-env-version -+ doom-modeline-mu4e -+ doom-modeline-irc -+ doom-modeline-irc-stylize +- doom-modeline-height +- doom-modeline-bar-width +- doom-modeline-buffer-file-name-style +- doom-modeline-icon +- doom-modeline-major-mode-icon +- doom-modeline-major-mode-color-icon +- doom-modeline-buffer-state-icon +- doom-modeline-buffer-modification-icon +- doom-modeline-minor-modes +- doom-modeline-enable-word-count +- doom-modeline-buffer-encoding +- doom-modeline-indent-info +- doom-modeline-checker-simple-format +- doom-modeline-vcs-max-length +- doom-modeline-persp-name +- doom-modeline-lsp +- doom-modeline-github +- doom-modeline-github-interval +- doom-modeline-env-version +- doom-modeline-mu4e +- doom-modeline-irc +- doom-modeline-irc-stylize + ** Faces -+ doom-modeline-buffer-path -+ doom-modeline-buffer-file -+ doom-modeline-buffer-modified -+ doom-modeline-buffer-major-mode -+ doom-modeline-buffer-minor-mode -+ doom-modeline-project-parent-dir -+ doom-modeline-project-dir -+ doom-modeline-project-root-dir -+ doom-modeline-highlight -+ doom-modeline-panel -+ doom-modeline-debug -+ doom-modeline-info -+ doom-modeline-warning -+ doom-modeline-urgent -+ doom-modeline-unread-number -+ doom-modeline-bar -+ doom-modeline-inactive-bar -+ doom-modeline-evil-emacs-state -+ doom-modeline-evil-insert-state -+ doom-modeline-evil-motion-state -+ doom-modeline-evil-normal-state -+ doom-modeline-evil-operator-state -+ doom-modeline-evil-visual-state -+ doom-modeline-evil-replace-state -+ doom-modeline-persp-name -+ doom-modeline-persp-buffer-not-in-persp +- doom-modeline-buffer-path +- doom-modeline-buffer-file +- doom-modeline-buffer-modified +- doom-modeline-buffer-major-mode +- doom-modeline-buffer-minor-mode +- doom-modeline-project-parent-dir +- doom-modeline-project-dir +- doom-modeline-project-root-dir +- doom-modeline-highlight +- doom-modeline-panel +- doom-modeline-debug +- doom-modeline-info +- doom-modeline-warning +- doom-modeline-urgent +- doom-modeline-unread-number +- doom-modeline-bar +- doom-modeline-inactive-bar +- doom-modeline-evil-emacs-state +- doom-modeline-evil-insert-state +- doom-modeline-evil-motion-state +- doom-modeline-evil-normal-state +- doom-modeline-evil-operator-state +- doom-modeline-evil-visual-state +- doom-modeline-evil-replace-state +- doom-modeline-persp-name +- doom-modeline-persp-buffer-not-in-persp diff --git a/modules/ui/nav-flash/README.org b/modules/ui/nav-flash/README.org index b8a23ff07..694c7edbf 100644 --- a/modules/ui/nav-flash/README.org +++ b/modules/ui/nav-flash/README.org @@ -1,37 +1,64 @@ -#+TITLE: ui/nav-flash -#+DATE: June 4, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui nav-flash +#+subtitle: Blink after big motions +#+created: June 04, 2017 +#+since: 2.0.0 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] - -* Description +* Description :unfold: This module flashes the line around the cursor after any significant motion, to make it easy to follow after big operations. #+begin_quote -Tremendously helpful on large, 1600p+ or 4K displays. + πŸ’‘ Tremendously helpful on large, 1600p+ or 4K displays. #+end_quote -** Plugins -+ [[https://github.com/rolandwalker/nav-flash][nav-flash]] +** Maintainers +- [[doom-user:][@hlissner]] -* Prerequisites -This module has no dependencies. +[[doom-contrib-maintainer:][Become a maintainer?]] -* Configuration -By default, ~nav-flash~ will be triggered whenever ~recenter~ is called or an -entry is added to the jump-list (managed by better-jumper). +** Module flags +/This module has no flags./ -~recenter~ is called after many hooks and commands, such as: +** Packages +- [[doom-package:][nav-flash]] -+ better-jumper-post-jump-hook -+ rtags-after-find-file-hook -+ org-follow-link-hook -+ imenu-after-jump-hook -+ counsel-grep-post-action-hook -+ dumb-jump-after-jump-hook +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* Usage +By default, [[doom-package:][nav-flash]] will be triggered whenever [[fn:][recenter]] is called or an entry +is added to the jump-list (managed by [[doom-package:][better-jumper]]). + +[[fn:][recenter]] is called after many hooks and commands, such as: +- [[var:][better-jumper-post-jump-hook]] +- [[var:][rtags-after-find-file-hook]] +- [[var:][org-follow-link-hook]] +- [[var:][imenu-after-jump-hook]] +- [[var:][counsel-grep-post-action-hook]] +- [[var:][dumb-jump-after-jump-hook]] + +* 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 diff --git a/modules/ui/neotree/README.org b/modules/ui/neotree/README.org index efbf410c1..66dc0b446 100644 --- a/modules/ui/neotree/README.org +++ b/modules/ui/neotree/README.org @@ -1,9 +1,58 @@ -#+TITLE: :evil neotree +# -*- mode: doom-docs-org -*- +#+title: :ui neotree +#+subtitle: NERDTree for evil nerds +#+created: May 11, 2018 +#+since: 21.12.0 +* Description :unfold: This module brings a side panel for browsing project files, inspired by vim's NERDTree. #+begin_quote -Sure, there's dired and projectile, but sometimes I'd like a bird's eye view of -a project. + πŸ’‘ Sure, there's [[doom-package:][dired]] and [[doom-package:][projectile]], but sometimes I'd like a bird's eye view + of a project. +#+end_quote + +** Maintainers +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][neotree]] + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] #+end_quote diff --git a/modules/ui/ophints/README.org b/modules/ui/ophints/README.org index 49868b9b0..40cb51b44 100644 --- a/modules/ui/ophints/README.org +++ b/modules/ui/ophints/README.org @@ -1,23 +1,57 @@ -#+TITLE: ui/ophints -#+DATE: June 4, 2017 -#+SINCE: v2.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui ophints +#+subtitle: An indicator for β€œwhat did I just do?” +#+created: June 04, 2017 +#+since: 2.0.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - -* Description +* Description :unfold: This module provides op-hints (operation hinting), i.e. visual feedback for certain operations. It highlights regions of text that the last operation (like yank) acted on. -Uses ~evil-goggles~ for evil users and ~volatile-highlights~ otherwise. +Uses [[doom-package:][evil-goggles]] for evil users and [[doom-package:][volatile-highlights]] otherwise. -** Module Flags -This module provides no flags. +** Maintainers +- [[doom-user:][@hlissner]] -** Plugins -+ [[https://github.com/edkolev/evil-goggles/][evil-goggles]]* -+ [[https://github.com/k-talo/volatile-highlights.el][volatile-highlights]]* +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][evil-goggles]] if [[doom-module:][:editor evil]] +- [[doom-package:][volatile-highlights]] unless [[doom-module:][:editor evil]] + +** 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 diff --git a/modules/ui/popup/README.org b/modules/ui/popup/README.org index 38efc7ccc..1e2bbc029 100644 --- a/modules/ui/popup/README.org +++ b/modules/ui/popup/README.org @@ -1,21 +1,10 @@ -#+TITLE: ui/popup -#+DATE: January 6, 2018 -#+SINCE: v2.0.9 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui popup +#+subtitle: Tame sudden yet inevitable temporary windows +#+created: January 06, 2018 +#+since: 21.12.0 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] - - [[#set-popup-rule-and-set-popup-rules][~set-popup-rule!~ and ~set-popup-rules!~]] - - [[#disabling-hidden-mode-line-in-popups][Disabling hidden mode-line in popups]] -- [[#appendix][Appendix]] - - [[#commands][Commands]] - - [[#library][Library]] - - [[#hacks][Hacks]] - -* Description +* Description :unfold: This module provides a customizable popup window management system. Not all windows are created equally. Some are less important. Some I want gone @@ -23,41 +12,84 @@ once they have served their purpose, like code output or a help buffer. Others I want to stick around, like a scratch buffer or org-capture popup. More than that, popups ought to be the second class citizens of my editor; -spawned off to the side, discarded with the push of a button (e.g. =ESC= or -=C-g=), and easily restored if I want to see them again. Of course, this system -should clean up after itself and kill off buffers I mark as transient. +spawned off to the side, discarded with the push of a button (e.g. [[kbd:][ESC]] or [[kbd:][C-g]]), +and easily restored if I want to see them again. Of course, this system should +clean up after itself and kill off buffers I mark as transient. -** Module Flags -+ =+all= Enables fallback rules to ensure all temporary/special buffers (whose - name begins with a space or asterix) are treated as popups. -+ =+defaults= Enables reasonable default popup rules for a variety of buffers. +** Maintainers +- [[doom-user:][@hlissner]] -* Prerequisites -This module has no external prerequisites. +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +all :: + Enable fallback rules to ensure all temporary/special buffers (whose name + begins with a space or asterix) are treated as popups. +- +defaults :: + Enable reasonable default popup rules for a variety of buffers. + +** Packages +/This module doesn't install any packages./ + +** Hacks +- [[doom-package:][help-mode]] has been advised to follow file links in the buffer you were in + before entering the popup, rather than in a new window. +- [[doom-package:][wgrep]] buffers are advised to close themselves when aborting or committing + changes. +- [[doom-package:][persp-mode]] is advised to restore popup windows when loading a session from + file. +- Interactive calls to ~windmove-*~ commands (used by ~evil-window-*~ commands) + will ignore the ~no-other-window~ window parameter, allowing you to switch to + popup windows as if they're ordinary windows. +- ~balance-windows~ has been advised to close popups while it does its business, + then restore them afterwards. +- [[doom-package:][neotree]] advises ~balance-windows~, which causes major slow-downs when paired + with our ~balance-window~ advice, so we removes neotree's advice. +- [[doom-package:][org-mode]] is an ongoing (and huge) effort. It has a scorched-earth window + management system I'm not fond of. ie. it kills all windows and monopolizes + the frame. On top of that, it /really/ likes to use ~switch-to-buffer~ for + most of its buffer management, which completely bypasses + ~display-buffer-alist~. Some work has gone into reversing this. + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration ** ~set-popup-rule!~ and ~set-popup-rules!~ This module has two functions for defining your own rules for popups: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (set-popup-rule! PREDICATE &key IGNORE ACTIONS SIDE SIZE WIDTH HEIGHT SLOT VSLOT TTL QUIT SELECT MODELINE AUTOSAVE PARAMETERS) (set-popup-rules! &rest RULESETS) -#+END_SRC +#+end_src ~PREDICATE~ is a predicate function or regexp string to match against the buffer's name. You'll find comprehensive documentation on the other keywords in -~set-popup-rule!~'s docstring (=SPC h f set-popup-rule!=). +~set-popup-rule!~'s docstring ([[kbd:][SPC h f set-popup-rule!]]). #+begin_quote -Popup rules end up in ~display-buffer-alist~, which instructs ~display-buffer~ -calls on how to set up windows for buffers that meet certain conditions. -However, some plugins can avoid it entirely if they use ~set-buffer~ or -~switch-to-buffer~, which don't obey ~display-buffer-alist~. + πŸ“Œ Popup rules end up in ~display-buffer-alist~, which instructs + ~display-buffer~ calls on how to set up windows for buffers that meet + certain conditions. However, some plugins can avoid it entirely if they use + ~set-buffer~ or ~switch-to-buffer~, which don't obey ~display-buffer-alist~. #+end_quote Multiple popup rules can be defined with ~set-popup-rules!~: - -#+BEGIN_SRC emacs-lisp +#+begin_src emacs-lisp (set-popup-rules! '(("^ \\*" :slot -1) ; fallback rule for special buffers ("^\\*" :select t) @@ -66,7 +98,7 @@ Multiple popup rules can be defined with ~set-popup-rules!~: ("^\\*Help" :slot -1 :size 0.2 :select t) ("^\\*doom:" :size 0.35 :select t :modeline t :quit t :ttl t))) -#+END_SRC +#+end_src Omitted parameters in a ~set-popup-rules!~ will use the defaults set in ~+popup-defaults~. @@ -75,66 +107,55 @@ Omitted parameters in a ~set-popup-rules!~ will use the defaults set in By default, the mode-line is hidden in popups. To disable this, you can either: 1. Change the default ~:modeline~ property in ~+popup-defaults~: - - #+BEGIN_SRC emacs-lisp - ;; add to $DOOMDIR/config.el + #+begin_src emacs-lisp + ;; in $DOOMDIR/config.el (plist-put +popup-defaults :modeline t) - #+END_SRC + #+end_src - A value of ~t~ will instruct popups to use the default mode-line. Any - popup rule with a ~:modeline~ property can still override this. + A value of ~t~ will instruct popups to use the default mode-line. Any popup + rule with a ~:modeline~ property can still override this. 2. Completely disable management of the mode-line in popups: - - #+BEGIN_SRC emacs-lisp - ;; add to ~/.doom.d/config.el + #+begin_src emacs-lisp + ;; in $DOOMDIR/config.el (remove-hook '+popup-buffer-mode-hook #'+popup-set-modeline-on-enable-h) - #+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 -+ ~+popup/other~ (aliased to ~other-popup~, bound to ~C-x p~) -+ ~+popup/toggle~ -+ ~+popup/close~ -+ ~+popup/close-all~ -+ ~+popup/toggle~ -+ ~+popup/restore~ -+ ~+popup/raise~ +- ~+popup/other~ (aliased to ~other-popup~, bound to [[kbd:][C-x p]]) +- ~+popup/toggle~ +- ~+popup/close~ +- ~+popup/close-all~ +- ~+popup/toggle~ +- ~+popup/restore~ +- ~+popup/raise~ ** Library -+ Functions - + ~+popup-window-p WINDOW~ - + ~+popup-buffer-p BUFFER~ - + ~+popup-buffer BUFFER &optional ALIST~ - + ~+popup-parameter PARAMETER &optional WINDOW~ - + ~+popup-parameter-fn PARAMETER &optional WINDOW~ - + ~+popup-windows~ -+ Macros - + ~without-popups!~ - + ~save-popups!~ -+ Hooks - + ~+popup-adjust-fringes-h~ - + ~+popup|set-modeline~ - + ~+popup-close-on-escape-h~ - + ~+popup-cleanup-rules-h~ -+ Minor modes - + ~+popup-mode~ - + ~+popup-buffer-mode~ -** Hacks -+ =help-mode= has been advised to follow file links in the buffer you were in - before entering the popup, rather than in a new window. -+ =wgrep= buffers are advised to close themselves when aborting or committing - changes. -+ =persp-mode= is advised to restore popup windows when loading a session from - file. -+ Interactive calls to ~windmove-*~ commands (used by ~evil-window-*~ commands) - will ignore the ~no-other-window~ window parameter, allowing you to switch to - popup windows as if they're ordinary windows. -+ ~balance-windows~ has been advised to close popups while it does its business, - then restore them afterwards. -+ =neotree= advises ~balance-windows~, which causes major slow-downs when paired - with our ~balance-window~ advice, so we removes neotree's advice. -+ =org-mode= is an ongoing (and huge) effort. It has a scorched-earth window - management system I'm not fond of. ie. it kills all windows and monopolizes - the frame. On top of that, it /really/ likes to use ~switch-to-buffer~ for - most of its buffer management, which completely bypasses - ~display-buffer-alist~. Some work has gone into reversing this. +- Functions + - ~+popup-window-p WINDOW~ + - ~+popup-buffer-p BUFFER~ + - ~+popup-buffer BUFFER &optional ALIST~ + - ~+popup-parameter PARAMETER &optional WINDOW~ + - ~+popup-parameter-fn PARAMETER &optional WINDOW~ + - ~+popup-windows~ +- Macros + - ~without-popups!~ + - ~save-popups!~ +- Hooks + - ~+popup-adjust-fringes-h~ + - ~+popup|set-modeline~ + - ~+popup-close-on-escape-h~ + - ~+popup-cleanup-rules-h~ +- Minor modes + - ~+popup-mode~ + - ~+popup-buffer-mode~ diff --git a/modules/ui/tabs/README.org b/modules/ui/tabs/README.org index 7d4cb95f6..cdfe852ac 100644 --- a/modules/ui/tabs/README.org +++ b/modules/ui/tabs/README.org @@ -1,18 +1,50 @@ -#+TITLE: ui/tabs -#+DATE: July 12, 2019 -#+SINCE: v2.1 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui tabs +#+subtitle: Keep tabs on your buffers, literally +#+created: July 12, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - -* Description +* Description :unfold: This module adds an Atom-esque tab bar to the Emacs UI. -** Module Flags -This module provides no flags. +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/ema2159/centaur-tabs][centaur-tabs]] +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][centaur-tabs]] + +** 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 diff --git a/modules/ui/treemacs/README.org b/modules/ui/treemacs/README.org index 531489223..f9329a704 100644 --- a/modules/ui/treemacs/README.org +++ b/modules/ui/treemacs/README.org @@ -1,71 +1,88 @@ -#+TITLE: ui/treemacs -#+DATE: April 5, 2021 -#+SINCE: v2.0.4 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui treemacs +#+subtitle: A sidebar for all the things +#+created: June 09, 2018 +#+since: 21.12.0 (#669) -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] -- [[#troubleshooting][Troubleshooting]] +* Description :unfold: +[[doom-package:treemacs][Treemacs]] is a file and project explorer similar to NeoTree or vim's NerdTree, +but largely inspired by the Project Explorer in Eclipse. It shows the file +system outlines of your projects in a simple tree layout allowing quick +navigation and exploration, while also possessing basic file management +utilities. It includes: -* Description -[[https://github.com/Alexander-Miller/treemacs][Treemacs]] is a file and project explorer similar to NeoTree or vim’s NerdTree, but largely inspired by the Project Explorer in Eclipse. It shows the file system outlines of your projects in a simple tree layout allowing quick navigation and exploration, while also possessing basic file management utilities. -It includes: - -+ Integration with Git (when =:tools magit= is enabled) -+ Integration with Evil (when =:editor evil +everywhere= is enabled) -+ Workspace awareness (when =:ui workspaces= is enabled) +- Integration with Git (if [[doom-module:][:tools magit]] is enabled) +- Integration with Evil (if [[doom-module:][:editor evil +everywhere]] is enabled) +- Workspace awareness (if [[doom-module:][:ui workspaces]] is enabled) ** Maintainers -+ This module has no dedicated maintainers. +- [[doom-user:][@hlissner]] -** Module Flags -+ =+lsp= Enable ~lsp-treemacs~ integration and add shortcuts for common commands. +[[doom-contrib-maintainer:][Become a maintainer?]] -** Plugins -+ [[https://github.com/Alexander-Miller/treemacs/][treemacs]] -+ [[https://github.com/Alexander-Miller/treemacs/#treemacs-projectile][treemacs-projectile]] -+ =:editor evil +everywhere= - + [[https://github.com/Alexander-Miller/treemacs/#treemacs-evil][treemacs-evil]] -+ =:tools magit= - + [[https://github.com/Alexander-Miller/treemacs/#treemacs-magit][treemacs-magit]] -+ =:ui workspaces= - + [[https://github.com/Alexander-Miller/treemacs/#treemacs-persptreemacs-perspective][treemacs-persp]] -+ =+lsp= - + [[https://github.com/emacs-lsp/lsp-treemacs][lsp-treemacs]] +** Module flags +- +lsp :: + Enable ~lsp-treemacs~ integration and add shortcuts for common commands. -* Prerequisites -If ~+treemacs-git-mode~ is set to ~extended~ or ~deferred~ you will need to have -~python3~ installed. +** Packages +- [[doom-package:][lsp-treemacs]] if [[doom-module:][+lsp]] +- [[doom-package:][treemacs]] +- [[doom-package:][treemacs-evil]] if [[doom-module:][:editor evil +everywhere]] +- [[doom-package:][treemacs-magit]] if [[doom-module:][:tools magit]] +- [[doom-package:][treemacs-persp]] if [[doom-module:][:ui workspaces]] +- [[doom-package:][treemacs-projectile]] -* Features -The project bar can be opened using =SPC o p=. +** Hacks +/No hacks documented for this module./ -| Keybind | Description | -|---------+-----------------------------------------------------------------| -| =o s= | Open a horizontal dired buffer on the currently highlighted node | -| =o v= | Open a vertical dired buffer on the currently highlighted node | +** 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.]] + +If =python3= is present on your =$PATH=, [[doom-package:][treemacs]] will use it to display git +status for files. + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +The project bar can be opened using [[kbd:][SPC o p]]. + +| Keybind | Description | +|---------+------------------------------------------------------------------| +| [[kbd:][o s]] | Open a horizontal dired buffer on the currently highlighted node | +| [[kbd:][o v]] | Open a vertical dired buffer on the currently highlighted node | + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Configuration The variable ~+treemacs-git-mode~ sets the type of git integration that treemacs has. There are 3 possible values: +1. ~'simple~ (the default), which highlights only files based on their git + status, and is slightly faster, +2. ~'extended~, which highlights both files and directories, but requires + python, +3. ~'deferred~, same as extended, but highlights asynchronously. - 1. simple, which highlights only files based on their git status, and is - slightly faster, - 2. extended, which highlights both files and directories, but requires - python, - 3. deferred, same as extended, but highlights asynchronously. +#+begin_quote + 🚧 ~+treemacs-git-mode~ must be set before treemacs is loaded. +#+end_quote -the default being simple +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] -This must be set before treemacs has loaded. +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] -* TODO Troubleshooting -# Common issues and their solution, or places to look for help. +* TODO Appendix +#+begin_quote + πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/ui/unicode/README.org b/modules/ui/unicode/README.org index 82de5312c..dfb9e880f 100644 --- a/modules/ui/unicode/README.org +++ b/modules/ui/unicode/README.org @@ -1,77 +1,97 @@ -#+TITLE: ui/unicode -#+DATE: June 8, 2020 -#+SINCE: v2.0 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui unicode +#+subtitle: Extended unicode support for various languages +#+created: June 08, 2020 +#+since: 2.0.0 +* Description :unfold: +This module extends Doom's ability to display non-English unicode. It is +primarily useful for non-English Emacs users, for whom Doom's built-in unicode +support in insufficient. -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#getting-fonts-with-good-coverage][Getting fonts with good coverage]] - - [[#advanced-configuration][Advanced configuration]] -- [[#troubleshooting][Troubleshooting]] - - [[#emacs-daemon-mode][Emacs daemon mode]] - -* Description -This module extends Doom's ability to display non-English unicode. -It is primarily useful for non-English Emacs users, for whom Doom's built-in unicode support in insufficient. - -This module relies on the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package. It tries to setup the default emacs fontset to cover as many unicode glyphs as possible by scanning all available glyphs from all available fonts. - -When this module is enabled... - -+ Emacs will prefer to use the ~doom-unicode-font~ font to display non-latin glyphs if it provides coverage for them. -+ The first time you run Emacs a unicode cache will be generated -- this will take a while! -+ The cache will be regenerated every time Emacs is made aware of new fonts or you change the font configuration e.g. by modifying ~doom-unicode-font~. -+ The cache will be stored and should not be regenerated unless font-related configuration or the versions of relevant packages changes. +This module relies on the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package. It tries to setup the default +emacs fontset to cover as many unicode glyphs as possible by scanning all +available glyphs from all available fonts. +When this module is enabled: +- Emacs will prefer to use the ~doom-unicode-font~ font to display non-latin + glyphs if it provides coverage for them. +- The first time you run Emacs a unicode cache will be generated -- this will + take a while! +- The cache will be regenerated every time Emacs is made aware of new fonts or + you change the font configuration e.g. by modifying ~doom-unicode-font~. +- The cache will be stored and should not be regenerated unless font-related + configuration or the versions of relevant packages changes. ** Maintainers -This module has no dedicated maintainers. +*This module needs a maintainer.* [[doom-contrib-maintainer:][Become a maintainer?]] -** Module Flags -This module provides no flags. +** Module flags +/This module has no flags./ -** Plugins -+ [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] +** Packages +- [[doom-package:][unicode-fonts]] -* Prerequisites -This module has no prerequisites. +** Hacks +/No hacks documented for this module./ -* Features -# An in-depth list of features, how to use them, and their dependencies. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Configuration -The first font that will be analyzed to see if it contains the glyphs of non-latin characters will be ~doom-unicode-font~. To set this font place -#+BEGIN_SRC elisp +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote + +The first font that will be analyzed to see if it contains the glyphs of +non-latin characters will be ~doom-unicode-font~: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq doom-unicode-font (font-spec :family "Fira Mono")) -#+END_SRC -in your private =config.el= file. If your ~doom-font~ provides good unicode coverage you just set -#+BEGIN_SRC elisp +#+end_src + +If your ~doom-font~ provides good unicode coverage use: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (setq doom-unicode-font doom-font) -#+END_SRC -If your font does not provide some glyphs, this package will try its best to find another font that does. +#+end_src + +If your font does not provide some glyphs, this package will try its best to +find another font that does. ** Getting fonts with good coverage -A list of fonts with good unicode coverage can be found on the page of the [[https://github.com/rolandwalker/unicode-fonts#minimum-useful-fonts][unicode-fonts]] package. +A list of fonts with good unicode coverage can be found on the page of the +[[https://github.com/rolandwalker/unicode-fonts#minimum-useful-fonts][unicode-fonts]] package. ** Advanced configuration -Consult the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package documentation for a description of more advanced configuration. The configuration should be placed, as usual, in your private =config.el= wrapped in an ~(after! unicode-fonts)~ block. The variable ~unicode-fonts-blocks~ contains a list of all unicode block names and their character ranges. The default fonts to search for glyphs are in the variable ~unicode-fonts-block-font-mapping~. +Consult the [[https://github.com/rolandwalker/unicode-fonts][unicode-fonts]] package documentation for a description of more +advanced configuration. The configuration should be placed, as usual, in +=$DOOMDIR/config.el= wrapped in an ~(after! unicode-fonts)~ block. The variable +~unicode-fonts-blocks~ contains a list of all unicode block names and their +character ranges. The default fonts to search for glyphs are in the variable +~unicode-fonts-block-font-mapping~. -If you want to use the font =Symbola= for =Miscellaneous Symbols= by default you could add -#+BEGIN_SRC elisp +If you want to use the font =Symbola= for =Miscellaneous Symbols= by default +use: +#+begin_src emacs-lisp +;; in $DOOMDIR/config.el (after! unicode-fonts (push "Symbola" (cadr (assoc "Miscellaneous Symbols" unicode-fonts-block-font-mapping)))) -#+END_SRC -to your =config.el=. +#+end_src -If you want to redefine several blocks an efficient way would be -#+BEGIN_SRC elisp +If you want to redefine several blocks an efficient way would be: +#+begin_src emacs-lisp (after! unicode-fonts (dolist (unicode-block '("Mathematical Alphanumeric Symbols" "Mathematical Operators" @@ -81,12 +101,20 @@ If you want to redefine several blocks an efficient way would be "Miscellaneous Symbols and Arrows" "Miscellaneous Symbols and Pictographs")) (push "DejaVu Math TeX Gyre" (cadr (assoc unicode-block unicode-fonts-block-font-mapping))))) -#+END_SRC +#+end_src You can find a list of fonts available to emacs using ~M-x counsel-fonts~. - * Troubleshooting -# Common issues and their solution, or places to look for help. -** TODO Emacs daemon mode -Currently this module may fail setup fonts when emacs is run in daemon mode. See [[https://github.com/hlissner/doom-emacs/issues/3328][Bug 3328]]. +[[doom-report:][Report an issue?]] + +** TODO Emacs daemon mode ([[doom-ref:][#3328]]) +This module may fail to setup fonts when emacs is run in a daemon session. + +* 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 diff --git a/modules/ui/vc-gutter/README.org b/modules/ui/vc-gutter/README.org new file mode 100644 index 000000000..3830fc007 --- /dev/null +++ b/modules/ui/vc-gutter/README.org @@ -0,0 +1,56 @@ +# -*- mode: doom-docs-org -*- +#+title: :ui vc-gutter +#+subtitle: Get your diff out of the gutter +#+created: June 26, 2018 +#+since: 21.12.0 + +* Description :unfold: +This module displays a diff of the current file (against HEAD) in the fringe. +Supports Git, Svn, Hg, and Bzr. + +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ + +** Packages +- [[doom-package:][git-gutter-fringe]] + +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +This module requires any of Git, Svn, Hg, and/or Bazaar to get gutter diffs in +projects version controlled by them. + +* TODO Usage +#+begin_quote +πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote +πŸ”¨ This module has no configuration documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* Troubleshooting +/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 diff --git a/modules/ui/vi-tilde-fringe/README.org b/modules/ui/vi-tilde-fringe/README.org index 4c43c838c..e7feca1fc 100644 --- a/modules/ui/vi-tilde-fringe/README.org +++ b/modules/ui/vi-tilde-fringe/README.org @@ -1,42 +1,61 @@ -#+TITLE: ui/vi-tilde-fringe -#+DATE: May 22, 2021 -#+SINCE: v2.0.5 -#+STARTUP: inlineimages nofold +# -*- mode: doom-docs-org -*- +#+title: :ui vi-tilde-fringe +#+subtitle: Fringe tildes beyond EOB +#+created: September 24, 2017 +#+since: 2.0.6 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#maintainers][Maintainers]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] -- [[#prerequisites][Prerequisites]] -- [[#configuration][Configuration]] - -* Description -Displays a tilde(~) in the left fringe to indicate an empty line, similar to Vi. +* Description :unfold: +Displays a tilde(~) in the left fringe to indicate an empty line, similar to Vi. ** 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/syl20bnr/vi-tilde-fringe][vi-tilde-fringe]] +** Module flags +/This module has no flags./ -* Prerequisites -This module has no prerequisites. +** Packages +- [[doom-package:][vi-tilde-fringe]] + +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* Usage +Nothing more needs to be done once the module is activated. Tildes will become +visible in all buffers, after EOB. * Configuration -By default, doom activates ~vi-tilde-fringe-mode~ for ~prog-mode~, ~text-mode~ and ~conf-mode~. To change this to your liking, you can remove any of the modes from the list - +By default, doom activates ~vi-tilde-fringe-mode~ for ~prog-mode~, ~text-mode~ +and ~conf-mode~. To change this to your liking, you can remove any of the modes +from the list: #+begin_src emacs-lisp -;; in ~/.doom.d/config.el +;; in $DOOMDIR/config.el (remove-hook 'text-mode-hook #'vi-tilde-fringe-mode) #+end_src -or add new modes where you would like ~vi-tilde-fringe-mode~ enabled. - +Or add new modes where you would like ~vi-tilde-fringe-mode~ enabled: #+begin_src emacs-lisp -;; in ~/.doom.d/config.el +;; in $DOOMDIR/config.el (add-hook 'org-mode-hook #'vi-tilde-fringe-mode) #+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 diff --git a/modules/ui/window-select/README.org b/modules/ui/window-select/README.org index 25e5c0483..008414326 100644 --- a/modules/ui/window-select/README.org +++ b/modules/ui/window-select/README.org @@ -1,66 +1,91 @@ -#+TITLE: ui/window-select -#+DATE: October 8, 2017 -#+SINCE: v2.0.7 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui window-select +#+subtitle: Visually switch windows +#+created: October 08, 2017 +#+since: 2.0.7 (#237) -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#packages][Packages]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] -- [[#configuration][Configuration]] - - [[#ace-window][ace-window]] - - [[#switch-window][switch-window]] - -* Description +* Description :unfold: This module provides several methods for selecting windows without the use of -the mouse or spatial navigation (e.g. =C-w {h,j,k,l}=). +the mouse or spatial navigation (e.g. [[kbd:][C-w {h,j,k,l}]]). -The command ~other-window~ is remapped to either ~switch-window~ or -~ace-window~, depending on which backend you've enabled. It is bound to ~C-x o~ -(and ~C-w C-w~ for evil users). +The command ~other-window~ is remapped to either [[doom-package:][switch-window]] or [[doom-package:][ace-window]], +depending on which backend you've enabled. It is bound to [[kbd:][C-x o]] (and [[kbd:][C-w C-w]] for +evil users). -It also provides numbered windows and selection with the ~winum~ package, if -desired. Evil users can jump to window N in =C-w = (where N is a number -between 0 and 9). Non evil users have =C-x w = instead. +It also provides numbered windows and selection with the [[doom-package:][winum]] package, if +desired. Evil users can jump to window N in [[kbd:][C-w ]] (where N is a number between +0 and 9). Non evil users have [[kbd:][C-x w ]] instead. -** Module Flags -+ =+switch-window= Use the switch-window package as the backend, instead of - ace-window (avy). -+ =+numbers= Enable numbered windows and window selection (using winum). +** Maintainers +/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +- +numbers :: + Enable numbered windows and window selection (using [[doom-package:][winum]]). +- +switch-window :: + Use the [[doom-package:][switch-window]] package as the backend, instead of ace-window ([[doom-package:][avy]]). ** Packages -+ [[https://github.com/dimitri/switch-window][switch-window]] (if =+switch-window=) -+ [[https://github.com/abo-abo/ace-window][ace-window]] (if =+switch-window= isn't enabled) -+ [[https://github.com/deb0ch/emacs-winum][winum]] (if =+numbers=) +- [[doom-package:][ace-window]] unless [[doom-module:][+switch-window]] +- [[doom-package:][switch-window]] if [[doom-module:][+switch-window]] +- [[doom-package:][winum]] if [[doom-module:][+numbers]] -* Prerequisites -This module has no additional dependencies. +** Hacks +/No hacks documented for this module./ + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ This module has no usage documentation yet. [[doom-contrib-module:][Write some?]] +#+end_quote + +* TODO Configuration +#+begin_quote + πŸ”¨ /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* TODO Features -* Configuration This module provides two backends, both providing the same functionality, but -with different visual cues. They are =ace-window= and =switch-window=. +with different visual cues. They are [[doom-package:][ace-window]] and [[doom-package:][switch-window]]. ** ace-window The first character of the buffers changes to a highlighted, user-selectable character. - + Pros: the content of the buffers are always visible. - + Cons: The display characters are small and difficult to see (see below for a way to enlarge them). +- *Pros:* the content of the buffers are always visible. +- *Cons:* The display characters are small and difficult to see (see below for a + way to enlarge them). -**** Custom font-face example -This changes the ace-window display to show a white letter with a red background. The box attribute adds some padding. -#+BEGIN_SRC elisp +*** Custom font-face example +This changes the ace-window display to show a white letter with a red +background. The box attribute adds some padding: +#+begin_src emacs-lisp (custom-set-faces! '(aw-leading-char-face :foreground "white" :background "red" :weight bold :height 2.5 :box (:line-width 10 :color "red"))) -#+END_SRC +#+end_src ** switch-window Replaces the entire buffer with large letters. - + Pros: The displayed characters are /really/ easy to see. - + Cons: You can't see the contents of the buffers. +- *Pros:* The displayed characters are /really/ easy to see. +- *Cons:* You can't see the contents of the buffers. + +* Troubleshooting +/There are no known problems with this module./ [[doom-report:][Report one?]] + +* Frequently asked questions +/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]] + +* TODO Appendix +#+begin_quote +πŸ”¨ This module has no appendix yet. [[doom-contrib-module:][Write one?]] +#+end_quote diff --git a/modules/ui/workspaces/README.org b/modules/ui/workspaces/README.org index 55335b0ae..12ef9c727 100644 --- a/modules/ui/workspaces/README.org +++ b/modules/ui/workspaces/README.org @@ -1,45 +1,52 @@ -#+TITLE: ui/workspaces -#+DATE: February 4, 2017 -#+SINCE: v1.3 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui workspaces +#+subtitle: Tab emulation, persistence, & separate workspaces +#+created: February 20, 2017 +#+since: 2.0.0 -* Table of Contents :TOC: -- [[#description][Description]] - - [[#module-flags][Module Flags]] - - [[#packages][Packages]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#isolated-buffer-list][Isolated buffer-list]] - - [[#automatic-workspaces][Automatic workspaces]] - - [[#session-persistence][Session persistence]] - - [[#workspace-persistence][Workspace persistence]] -- [[#appendix][Appendix]] - - [[#commands--keybindings][Commands & Keybindings]] - - [[#api][API]] - -* Description -This module adds support for workspaces, powered by persp_mode, as well as a API +* Description :unfold: +This module adds support for workspaces, powered by [[doom-package:][persp-mode]], as well as a API for manipulating them. #+begin_quote -There are many ways to use workspaces. I spawn a workspace per task. Say I'm -working in the main workspace, when I realize there is a bug in another part of -my project. I open a new workspace and deal with it in there. In the meantime, I -need to check my email, so mu4e gets its own workspace. + πŸ’‘ There are many ways to use workspaces. I spawn a workspace per task. Say I'm + working in the main workspace, when I realize there is a bug in another part + of my project. I open a new workspace and deal with it in there. In the + meantime, I need to check my email, so mu4e gets its own workspace. -Once I've completed the task, I close the workspace and return to main. + Once I've completed the task, I close the workspace and return to main. #+end_quote -** Module Flags -This module provides no flags. +** Maintainers +- [[doom-user:][@hlissner]] + +[[doom-contrib-maintainer:][Become a maintainer?]] + +** Module flags +/This module has no flags./ ** Packages -+ [[https://github.com/Bad-ptr/persp-mode.el][persp-mode]] +- [[doom-package:][persp-mode]] -* Prerequisites -This module has no additional dependencies. +** TODO Hacks +#+begin_quote + πŸ”¨ This module's hacks haven't been documented yet. [[doom-contrib-module:][Document them?]] +#+end_quote + +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ + +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] + +/This module has no external requirements./ + +* TODO Usage +#+begin_quote + πŸ”¨ /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]] +#+end_quote -* Features ** Isolated buffer-list When persp-mode is active, ~doom-buffer-list~ becomes workspace-restricted. You can overcome this by using ~buffer-list~. @@ -47,8 +54,8 @@ can overcome this by using ~buffer-list~. ** Automatic workspaces A workspace is automatically created (and switched to) when you: -+ Create a new frame (with =make-frame=; bound to =M-N= by default). -+ Switch to a project using ~projectile-switch-project~. +- Create a new frame (with =make-frame=; bound to [[kbd:][M-N]] by default). +- Switch to a project using ~projectile-switch-project~. ** Session persistence By default, your session is autosaved when you quit Emacs (or disable @@ -63,26 +70,41 @@ If you'd like to save a specific workspace, use ~M-x +workspace/save~, which can be loaded into the current session (as another workspace) with ~M-x +workspace/load~. -* Appendix ** Commands & Keybindings Here is a list of available commands, their default keybindings (defined in -[[../../config/default/+evil-bindings.el][private/default/+bindings.el]]), and corresponding ex commands (if any -- defined -in [[../../editor/evil/+commands.el][private/default/+evil-commands.el]]). +[[../../config/default/+evil-bindings.el][config/default/+bindings.el]]), and corresponding ex commands (if any -- defined +in [[../../editor/evil/+commands.el][config/default/+evil-commands.el]]). -| command | key / ex command | description | -|-----------------------------------+----------------------------+------------------------------------------------------------| -| ~+workspace/new~ | =SPC TAB n= | Create a new, blank workspace | -| ~+workspace/display~ | =SPC TAB TAB= | Display open workspaces in the mode-line | -| ~+workspace/load~ | =SPC TAB l= | Load a saved workspace into the current session | -| ~+workspace/restore-last-session~ | =SPC TAB R= | Restore last session | -| ~+workspace/rename~ | =SPC TAB r= | Rename the current workspace | -| ~+workspace/save~ | =SPC TAB s= | Save the current workspace to a file | -| ~+workspace/switch-to~ | =SPC TAB .= | Switch to an open workspace | -| ~+workspace/other~ | =SPC TAB `= | Switch to last workspace | -| ~+workspace/switch-left~ | =SPC TAB [= / =[ w= / =gT= | Switch to previous workspace | -| ~+workspace/switch-right~ | =SPC TAB ]= / =] w= / =gt= | Switch to next workspace | -| ~+workspace/delete~ | =SPC TAB d= | Delete the current workspace | -| ~+workspace/kill-session~ | =SPC TAB x= / =:sclear= | Clears the current session (kills all windows and buffers) | +| command | key / ex command | description | +|-----------------------------------+----------------------+------------------------------------------------------------| +| ~+workspace/new~ | [[kbd:][SPC TAB n]] | Create a new, blank workspace | +| ~+workspace/display~ | [[kbd:][SPC TAB TAB]] | Display open workspaces in the mode-line | +| ~+workspace/load~ | [[kbd:][SPC TAB l]] | Load a saved workspace into the current session | +| ~+workspace/restore-last-session~ | [[kbd:][SPC TAB R]] | Restore last session | +| ~+workspace/rename~ | [[kbd:][SPC TAB r]] | Rename the current workspace | +| ~+workspace/save~ | [[kbd:][SPC TAB s]] | Save the current workspace to a file | +| ~+workspace/switch-to~ | [[kbd:][SPC TAB .]] | Switch to an open workspace | +| ~+workspace/other~ | [[kbd:][SPC TAB `]] | Switch to last workspace | +| ~+workspace/switch-left~ | [[kbd:][SPC TAB []] / [[kbd:][[ w]] / [[kbd:][gT]] | Switch to previous workspace | +| ~+workspace/switch-right~ | [[kbd:][SPC TAB ]]] / [[kbd:][] w]] / [[kbd:][gt]] | Switch to next workspace | +| ~+workspace/delete~ | [[kbd:][SPC TAB d]] | Delete the current workspace | +| ~+workspace/kill-session~ | [[kbd:][SPC TAB x]] / [[kbd:][:sclear]] | Clears the current session (kills all windows and buffers) | + +* 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's appendix is incomplete./ [[doom-contrib-module:][Write more?]] +#+end_quote ** API + ~+workspace-list~ -> list diff --git a/modules/ui/zen/README.org b/modules/ui/zen/README.org index 103ef2e29..2861091de 100644 --- a/modules/ui/zen/README.org +++ b/modules/ui/zen/README.org @@ -1,33 +1,23 @@ -#+TITLE: ui/zen -#+DATE: December 20, 2019 -#+SINCE: v3.0.0 -#+STARTUP: inlineimages +# -*- mode: doom-docs-org -*- +#+title: :ui zen +#+subtitle: Distraction-free mode for the eternally distracted +#+created: December 20, 2019 +#+since: 21.12.0 -* Table of Contents :TOC_3:noexport: -- [[#description][Description]] - - [[#usage][Usage]] - - [[#module-flags][Module Flags]] - - [[#plugins][Plugins]] - - [[#hacks][Hacks]] -- [[#prerequisites][Prerequisites]] -- [[#features][Features]] - - [[#distractions-free-mode][Distractions-free mode]] -- [[#configuration][Configuration]] - - [[#enable-fullscreen-on-activation][Enable fullscreen on activation]] - -* Description +* Description :unfold: This module provides two minor modes that make Emacs into a more comfortable writing or coding environment. Folks familiar with "distraction-free" or "zen" -modes from other editors -- or [[https://github.com/rnkn/olivetti][olivetti]], [[https://github.com/zk-phi/sublimity][sublimity]], and [[https://github.com/IdoMagal/Tabula-Rasa][tabula-rasa]] (Emacs +modes from other editors -- or [[doom-package:][olivetti]], [[doom-package:][sublimity]], and [[doom-package:][tabula-rasa]] (Emacs plugins) -- will feel right at home. These modes are: - -+ ~mixed-pitch-mode~ :: Which renders (most) text in a variable pitch font (see +- ~mixed-pitch-mode~ :: + Which renders (most) text in a variable pitch font (see ~doom-variable-pitch-font~). Unlike ~variable-pitch-mode~, this will not affect segments of text that are intended to remain in a fixed pitch font, such as code blocks or ASCII tables. -+ ~writeroom-mode~ :: Our all-in-one "zen" mode that will: +- ~writeroom-mode~ :: + Our all-in-one "zen" mode that will: 1. Center the current buffer. 2. Remove superfluous UI elements (like the modeline). 3. Activate ~mixed-pitch-mode~. @@ -35,22 +25,17 @@ These modes are: 5. And make the window's borders slightly thicker (see ~+zen-window-divider-size~). -** Usage -This module provides two entry points: +** Maintainers +- [[doom-user:][@hlissner]] -+ ~M-x +zen/toggle~ :: toggles ~writeroom-mode~ (restricted to the current - buffer). -+ ~M-x +zen/toggle-fullscreen~ :: toggles zen mode in full-screen mode (deletes - other windows and full screens the Emacs frame). +[[doom-contrib-maintainer:][Become a maintainer?]] -Invoke either command again to undo the change. +** Module flags +/This module has no flags./ -** Module Flags -This module provides no flags. - -** Plugins -+ [[https://github.com/joostkremers/writeroom-mode][writeroom-mode]] -+ [[https://gitlab.com/jabranham/mixed-pitch][mixed-pitch]] +** Packages +- [[doom-package:][mixed-pitch]] +- [[doom-package:][writeroom-mode]] ** Hacks + Doom has disabled all of writeroom-mode's "global" effects @@ -61,18 +46,37 @@ This module provides no flags. + ~text-scale~ has been advised to adjust ~visual-fill-column~'s margins, so its text won't "squeeze" as you scale it up (or "spill" when scaled down). -* Prerequisites -This module has no prerequisites. +** TODO Changelog +# This section will be machine generated. Don't edit it by hand. +/This module does not have a changelog yet./ -* Features -** Distractions-free mode -This can be activated with =SPC t z= for evil users. -Non-evil users can use =C-c t z= or 'M-x writeroom-mode'. +* Installation +[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]] -* Configuration -** Enable fullscreen on activation -#+BEGIN_SRC elisp -(setq writeroom-fullscreen-effect t) -#+END_SRC +/This module has no external requirements./ -Or fullscreen manually with =SPC t F= (or =F11= for non-evil users). +* Usage +This module provides two entry points: + +- ~M-x +zen/toggle~ (on [[kbd:][ t z]]): toggles ~writeroom-mode~ (restricted to + the current buffer). +- ~M-x +zen/toggle-fullscreen~ (on [[kbd:][ t Z]]): toggles zen mode in + full-screen mode (deletes other windows and full screens the Emacs frame). + +Invoke either command again to undo the change. + +* 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