doomemacs/modules/os/tty/README.org

#+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.
- Support for the [[https://sw.kovidgoyal.net/kitty/keyboard-protocol/][Kitty keyboard protocol]] in supported terminals.

** 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:kkp]]
- [[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