doomemacs/modules/os/tty/README.org

← [[doom-module-index:][Back to module index]]               ↙ [[doom-module-issues:::os tty][Issues]]  ↖ [[doom-module-source:os/tty][Source]]  ± [[doom-suggest-edit:][Suggest edits]]  ? [[doom-help-modules:][Help]]
--------------------------------------------------------------------------------
#+TITLE:    :os tty
#+SUBTITLE: Make TTY Emacs suck less
#+CREATED:  August 07, 2020
#+SINCE:    21.12.0

* Description :unfold:
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.

** 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
  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]].

** 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.]]

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 [[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
  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.

* 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

** 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
/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