merge: rewrite-docs
I've omitted docs/*.org from this merge, as there is still work left to do there, but I am pushing the module docs early so folks can benefit from the new docs sooner.
This commit is contained in:
Henrik Lissner
commit
1f8bf7accb
179 changed files with 13125 additions and 8630 deletions
16
modules/term/README.org
Normal file
16
modules/term/README.org
Normal file
|
|
@ -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?]]
|
||||
|
|
@ -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
|
||||
|
|
|
|||
61
modules/term/shell/README.org
Normal file
61
modules/term/shell/README.org
Normal file
|
|
@ -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
|
||||
50
modules/term/term/README.org
Normal file
50
modules/term/term/README.org
Normal file
|
|
@ -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
|
||||
|
|
@ -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-<version>=) and run
|
||||
the following:
|
||||
|
||||
#+BEGIN_SRC sh
|
||||
directory (usually =$HOME/.emacs.d/.local/packages/elpa/vterm-<version>=) 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-<version>/vterm-module.so=
|
||||
=$HOME/.emacs.d/.local/packages/elpa/vterm-<version>/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:][<leader> o t]]) -- Toggle vterm pop up window in the current
|
||||
project.
|
||||
- ~+vterm/here~ ([[kbd:][<leader> 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue