docs(:term): update READMEs to new format

modules/term/README.org

@@ -1,12 +1,11 @@
-← [[doom-module-index:][Back to module index]]                      ↙ [[doom-changelog-search:::term nil][Changelog]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
+← [[doom-module-index:][Back to module index]]                         ↖ [[doom-module-source:term][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
 --------------------------------------------------------------------------------
-#+TITLE:     :term
+#+TITLE:   :term
-#+CREATED:   August 1, 2021
+#+CREATED: August 01, 2021
-#+SINCE:     v21.12.0
+#+SINCE:   21.12.0
-#+SETUPFILE: ../../docs/.setupfile.org
 
 * Description
-What's an operating system without a terminal? The moduels in this category
+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]]

modules/term/eshell/README.org

@@ -1,65 +1,77 @@
-#+TITLE:   term/eshell
+← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::term eshell][Issues]]  ↖ [[doom-module-source:term/eshell][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
-#+DATE:    May 18, 2020
+--------------------------------------------------------------------------------
-#+SINCE:   v2.0
+#+TITLE:    :term eshell
-#+STARTUP: inlineimages nofold
+#+SUBTITLE: The elisp shell that works everywhere
+#+CREATED:  February 20, 2017
+#+SINCE:    2.0.0
 
-* Table of Contents :TOC_3:noexport:
+* Description :unfold:
-- [[#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
 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
+[[doom-contrib-maintainer:][Become a maintainer?]]
-This module provides no flags, but does gain auto-completion if =:completion
-company= is enabled.
 
-** Plugins
+** Module flags
-+ [[https://github.com/peterwvj/eshell-up][eshell-up]]
+/This module has no flags./
-+ [[https://github.com/xuchunyang/eshell-z][eshell-z]]
+
-+ [[https://github.com/tom-tan/esh-help][esh-help]]
+** Packages
-+ [[https://gitlab.com/bennya/shrink-path.el][shrink-path]]
+- [[doom-package:][eshell-did-you-mean]]
-+ [[https://github.com/xuchunyang/eshell-did-you-mean][eshell-did-you-mean]]
+- [[doom-package:][eshell-up]]
-+ =:completion company=
+- [[doom-package:][eshell-z]]
-  + [[https://gitlab.com/ambrevar/emacs-fish-completion][fish-completion]]
+- [[doom-package:][esh-help]]
-  + [[https://github.com/szermatt/emacs-bash-completion][bash-completion]]
+- [[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
+- Even with ~fish-completion-fallback-on-bash-p~ non-nil, fish must be installed
-  for bash completion to work. Workaround in =config.el=.
+  for bash completion to work. This has been circumvented.
-+ =eshell-did-you-mean= does not work on first invocation, so we manually invoke
+- [[doom-package:][eshell-did-you-mean]] does not work on first invocation, so we manually invoke
   it once.
 
-* Prerequisites
+** TODO Changelog
-[[https://fishshell.com/][=fish= shell]] for completions, falling back to [[https://www.gnu.org/software/bash/][=bash= shell]] if =fish= is not
+# This section will be machine generated. Don't edit it by hand.
-found. If neither shell is found, completions may not be available.
+/This module does not have a changelog yet./
 
-* Features
+* Installation
-+ Command completion with Company
+[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]
-+ =fish=-style prompt with Git integration
+
-+ [[https://github.com/rupa/z][=z=]]-like directory jumping
+This module requires either [[https://fishshell.com/][Fish shell]] or [[https://www.gnu.org/software/bash/][Bash]] for code completion.
-+ Command-not-found recommendations
+
+* 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
+By default, [[doom-package:][eshell]] sets the =$TERM= variable to ~"xterm-256color"~, which helps
-rendering various colours. As eshell is /not/ a terminal emulator, these will not
+with rendering various colours. As eshell is /not/ a terminal emulator, these
-always work 100%. Modifying =eshell-term-name= to your liking may help.
+will not always work 100%. Modifying ~eshell-term-name~ to your liking may help.
 
-* TODO Troubleshooting
+* 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

modules/term/shell/README.org

@@ -0,0 +1,62 @@
+← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::term shell][Issues]]  ↖ [[doom-module-source:term/shell][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
+--------------------------------------------------------------------------------
+#+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-issue:][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

modules/term/term/README.org

@@ -0,0 +1,51 @@
+← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::term term][Issues]]  ↖ [[doom-module-source:term/term][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
+--------------------------------------------------------------------------------
+#+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-issue:][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

modules/term/vterm/README.org

@@ -1,33 +1,51 @@
-#+TITLE:   term/vterm
+← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::term vterm][Issues]]  ↖ [[doom-module-source:term/vterm][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
-#+DATE:    January 16, 2019
+--------------------------------------------------------------------------------
-#+SINCE:   2.1
+#+TITLE:    :term vterm
-#+STARTUP: inlineimages
+#+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 :unfold:
-- [[#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
 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
+    - Emacs must be built with dynamic modules support,
-+ ~+vterm/here~ (=SPC o T=): Opens vterm in the current window
+    - and =vterm-module.so= must be compiled, which depends on =libvterm=,
+      =cmake=, and =libtool-bin=.
 
-** Module Flags
+    [[doom-package:][vterm]] will try to automatically build =vterm-module.so= when you first open
-This module provides no flags.
+    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
+** Maintainers
-+ [[https://github.com/akermu/emacs-libvterm][vterm]]
+- [[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 +53,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
+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
+doom info~ for ~MODULES~ next to "System features". If it's there, you're good
-good to go.
+to go.
 
-You can also check for =--with-modules= in the ~system-configuration-options~
+You can also check for ~--with-modules~ in the ~system-configuration-options~
-variable (=SPC h v 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 +66,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~
+- Ubuntu or Debian users: ~$ apt-get install libvterm-dev~
-+ ArchLinux or Manjaro: ~pacman -S libvterm~
+- ArchLinux or Manjaro: ~$ pacman -S libvterm~
-+ MacOS: ~libvterm~
+- MacOS: ~$ brew install libvterm~
-+ NixOS:
+- NixOS:
 
-  #+BEGIN_SRC nix
+  #+begin_src nix
   systemPackages = with pkgs; [
     # emacs    # no need for this, the next line includes emacs
     ((emacsPackagesNgGen 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
+  This already contains a version of =vterm-module.so=, so NixOS users need not
-  not compile the module themselves as described below.
+  compile the module themselves as described below.
   
-  Note: The =nixpkgs=-version that is used needs to be compatible with the rest
+  Note: The =nixpkgs=-version used must be compatible with the packages Doom
-  of the plugins installed in =doom=. Therefore it might be necessary to pull in
+  installs, so it might be necessary to pull in =emacs= and/or
-  =emacs= and/or =emacsPackagesNgGen= from =unstable= or another channel. Otherwise
+  =emacsPackagesNgGen= from =unstable= or another channel. Otherwise arbitrary
-  arbitrary functionality of =vterm= might not work.
+  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=
+- =make=
-+ =cmake=
+- =cmake=
-+ A C compiler like =gcc=
+- A C compiler like =gcc=
-+ An internet connection (=cmake= will download needed libraries)
+- 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.
+   e.g. To use a local build of libvterm instead of the included one:
-
+   #+begin_src emacs-lisp
-   #+BEGIN_SRC elisp
    (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
+   directory (usually =$HOME/.emacs.d/.local/packages/elpa/vterm-<version>=) and
-   the following:
+   run the following:
-
+   #+begin_src sh
-   #+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