\input texinfo

@comment %**start of header
@setfilename eat.info
@set UPDATED 15 December 2023
@set VERSION 0.9.4
@documentencoding UTF-8
@codequotebacktick on
@codequoteundirected on
@syncodeindex fn cp
@syncodeindex vr cp
@syncodeindex ky cp
@settitle Eat User Manual, version @value{VERSION}
@comment %**end of header

@copying
This manual is for Eat (version @value{VERSION}, @value{UPDATED}), a
terminal emulator for Emacs.

Copyright @copyright{}  2022, 2023  Akib Azmain Turja.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end copying

@dircategory Emacs
@direntry
* Eat: (eat).           Emulate A Terminal.
@end direntry

@titlepage
@title Eat User Manual
@subtitle For version @value{VERSION}
@author Akib Azmain Turja
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top
@top Eat Manual
@insertcopying
@end ifnottex

@menu
Introduction
* Intro::               What is Eat?
* Hello Terminal::      Starting Eat's terminal for the first time.
* Project-local Terminal::  One project, one terminal.
* Eshell Terminal::     Eat's terminal emulation in Eshell.

Basic Operations
* Keyboard::            Most keyboard keys are captured by Eat.
* Mouse::               Eat supports mouse.
* Input Modes::         Input modes for various use-cases.
* Password Input::      Safely inputting credentials.

Advanced Customizations
* Shell Integration::   Getting the most from Eat and your shell.
* Querying Before Kill::  Confirming before you kill your terminal.
* Changing Shell::      Changing the default shell.
* Display::             The region where everything is shown.
* Scrollback::          Region for things that went out of display.
* Cursor Types::        Cursor can displayed in many forms.
* Mouse Tracking::      Eat tracks mouse, but this can be changed.
* Clipboard::           Integrating kill ring with terminal.
* Colors::              Eat can show more than sixteen million colors.
* Fonts::               Eat can show up to sixteen different fonts.
* Sixel::               Eat can render Sixel graphics.
* Blinking Text::       Annoying blinking texts.
* Performance Tuning::  Fine tuning to maximize performance.

Recovering from Problems
* Common Problems::     Common problem, and fixes.
* Reporting Bugs::      How to report problems?
* Tracing the Terminal::  Gathering some crucial information to
                          reproduce a bug.

Appendices
* GNU General Public License::  Copying condition for Eat.
* GNU Free Documentation License::  Copying conditions of this manual.
* Index::               A list of various things.
@end menu

@part Part I:@* Introduction

@node Intro
@cindex introduction
@chapter Introduction

@abbr{Eat, Emulate A Terminal} is a terminal emulator for Emacs.  It
emulates a XTerm-like terminal, just like many other terminal
emulators.  But it has some key features that make Eat distinct from
other terminal emulators.

Firstly, it's in Emacs, which means you don't need to leave the
comfort of Emacs to use terminal.

Secondly, it's easy and convenient to use.  It is tries to stay out of
your way, allowing you to maximize your productivity.

Finally, special care has been taken while designing the keybindings,
so that the terminal doesn't conflict with Emacs default keybindings
on both graphical display and text display, while still allowing you
to run full screen programs like Emacs within the terminal.

@node Hello Terminal
@cindex hello terminal
@cindex terminal, hello
@chapter Hello Terminal

@findex eat
The terminal can be started with @kbd{M-x eat}.  It'll create a
terminal and run the default shell
(@pxref{Interactive Shell,,, emacs, GNU Emacs Manual}) in it.  You
should get a shell prompt and be able to write shell commands and
execute them.  Full screen programs like @samp{htop}, @samp{lynx} and
Emacs will work inside it, just like any other terminal.  (If the
terminal doesn't work as expected, @pxref{Common Problems}.)

If an Eat terminal already exists, @kbd{M-x eat} will switch to it.
To create a new terminal, call it with a prefix argument like this,
@kbd{C-u M-x eat}.

If you give it a numeric prefix argument N, for example
@kbd{C-u 42 M-x eat}, it'll switch to a terminal in the buffer
@file{*eat*<N>}, @file{*eat*<42>} for example, or it'll create a new
terminal if that buffer doesn't exist.

If you give it double prefix argument, for example
@kbd{C-u C-u M-x eat}, you'll be prompted for the program or shell
command to run, and it'll be run in a newly created terminal.

@node Project-local Terminal
@cindex project-local terminal
@cindex terminal, project-local
@cindex project's terminal
@cindex project terminal
@cindex terminal, project
@chapter Project-local Terminal

@findex eat-project
Usually, you don't use a single terminal for everything, instead you
open a terminal for each project that needs it.  So there is command
named @command{eat-project}.  It opens a new terminal in project root
directory, or switches to a already existing project terminal.  It too
accepts prefix argument, just like the ordinary @command{eat} command.

@node Eshell Terminal
@cindex eshell terminal
@cindex terminal, eshell
@cindex eshell terminal emulation
@cindex terminal emulation, eshell
@cindex eat, eshell
@cindex eshell, eat
@cindex eshell
@chapter Eshell Terminal Emulation

Eat also supports terminal emulation outside Eat's terminal.  So you
can emulate terminal in Eshell (@pxref{Top,,, eshell, Eshell manual})
with Eat.  After configuring Eshell to use Eat for terminal emulation,
you can run any full screen terminal program in Eshell.

@findex eat-eshell-mode
To enable terminal emulation in Eshell, enable the global minor mode
@command{eat-eshell-mode}.  It will enable Eat's terminal emulation in
Eshell.  To disable the terminal emulation, disable the minor mode.

You can't toggle the global minor mode while any Eshell command is
running, so terminate any Eshell command or wait them to finish before
toggling the mode.

Unless stated otherwise, everything described in this manual about
Eat terminal also applies to Eshell terminal emulation.

You might also want to set @code{eshell-visual-commands} user option
to nil, since they'll work in Eshell when @code{eat-eshell-mode} is
enabled.

If you want to run Eshell visual commands with Eat, you can enable the
global minor mode @command{eat-eshell-visual-command-mode}.

@part Part II:@* Basic Operations

@node Keyboard
@cindex keyboard
@chapter Keyboard

Just like any other text terminal, the primary interaction device with
Eat terminal is the keyboard.  Eat forwards all supported keyboard
events like @kbd{a}, @kbd{E}, @kbd{RET}, @kbd{C-a} to the terminal.

However, this conflict with Emacs keybinding conventions, and makes it
almost impossible to call any other Emacs command.  So, by default,
Eat doesn't intercept the key sequences beginning with the following
keys and lets Emacs to handle them: @kbd{C-\}, @kbd{C-c}, @kbd{C-x},
@kbd{C-g}, @kbd{C-h}, @kbd{C-M-c}, @kbd{C-u}, @kbd{C-q}, @kbd{M-x},
@kbd{M-:}, @kbd{M-!} and @kbd{M-&}.

To input the above key sequences, prefix them with @kbd{C-q}.
@kbd{C-q} reads the next event and sends to directly to the terminal.
For example, to input @kbd{M-:}, use the key sequence @kbd{C-q M-:}.

For an alternative way to input these exceptional characters,
@pxref{Char Mode}.

@node Mouse
@cindex mouse
@chapter Mouse

Eat supports mouse tracking.  That means in programs like Emacs,
@samp{htop}, etc, that support mouse, you can hover and click on
text and buttons.  You can also use your mouse wheel to scroll text,
if the program supports it.

@xref{Mouse Tracking} to configure mouse tracking.

@node Input Modes
@cindex input modes
@cindex modes, input
@cindex keybinding modes
@cindex modes, keybinding
@chapter Input Modes

By default, Eat forwards all supported keys to terminals, except some
exceptions.  It is possible to input them with @kbd{C-q}, but it is
not very convenient.

To conveniently input those character, they should be bound to input
themselves to the terminal (i.e. pressing @kbd{M-x} will input
@kbd{M-x}, bypassing Emacs).  But this is conflicts with Emacs's
default keybindings, so this can't done, at least by default.

To overcome the problem, Eat implements several ``input modes''.  Each
input mode has a different set of keybindings for different
applications.

@anchor{Semi-char Mode}
@cindex semi-char mode
@cindex mode, semi-char
@cindex keybindings, semi-char mode
@cindex keybinding mode, semi-char
@cindex input mode, semi-char
@section Semi-char Mode

``Semi-char mode'' is the default input mode of Eat.  This works for
most inputs.  It forwards all keys, except @kbd{C-\}, @kbd{C-c},
@kbd{C-x}, @kbd{C-g}, @kbd{C-h}, @kbd{C-M-c}, @kbd{C-u}, @kbd{M-x},
@kbd{C-q}, @kbd{M-:}, @kbd{M-!}, @kbd{M-&} and some other keys, Emacs
handles them.

@cindex inputting exceptional characters
@kindex C-q @r{(``semi-char mode'')}
To input these exceptions, there is a key @kbd{C-q}.  This reads the
next input event and sends that as the input.  For example, the key
sequences @kbd{C-q M-:} inputs @kbd{M-:}, @kbd{C-q C-g} inputs
@kbd{C-g}.

Input methods (@pxref{Input Methods,,, emacs, GNU Emacs Manual}) work
in this mode, so, unlike Term (@pxref{Terminal emulator, Emacs
Terminal Emulator, Emacs Terminal Emulator, emacs, GNU Emacs Manual}),
Emacs built-in terminal emulator, you can still input any character.

@kindex C-c C-c @r{(``semi-char mode'')}
@kindex C-c C-k @r{(``semi-char mode'')}
In ``semi-char mode'', @kbd{C-c C-c} sends a @kbd{C-c}, just for
convenience, and @kbd{C-c C-k} kills the terminal program.

@cindex customizing semi-char mode
@cindex customizing semi-char mode keys
@cindex customizing semi-char mode keybindings
@cindex mode, semi-char, customizing
@cindex keybindings, semi-char mode, customizing
@cindex keybinding mode, semi-char, customizing
@cindex input mode, semi-char, customizing
@cindex mode, semi-char, adding exceptions
@cindex keybindings, semi-char mode, adding exceptions
@cindex keybinding mode, semi-char, adding exceptions
@cindex input mode, semi-char, adding exceptions
@cindex mode, semi-char, exception, add
@cindex keybindings, semi-char mode, exception, add
@cindex keybinding mode, semi-char, exception, add
@cindex input mode, semi-char, exception, add
@vindex eat-semi-char-non-bound-keys
@vindex eat-eshell-semi-char-non-bound-keys
You can customize the exceptions by customizing the user option
@code{eat-semi-char-non-bound-keys}, and
@code{eat-eshell-semi-char-non-bound-keys} for Eshell integration.
Both user options contain a list of keys of form @code{[@var{key}]},
where @var{key} is a key not to bind.  @var{key} mustn't contain meta
modifier.  To not bind a key with meta modifier, use a vector of form
@code{[?\e @var{key}]}, where @var{key} is the key without meta
modifier.  These user options contain all the ``semi-char'' mode
exceptions listed above, plus some more exceptions.

@findex eat-update-semi-char-mode-map
@findex eat-eshell-update-semi-char-mode-map
@findex eat-reload
If you set the user options manually (for example, with @code{setq}),
you must call @code{eat-update-semi-char-mode-map} or
@code{eat-eshell-update-semi-char-mode-map} respectively, and finally
reload Eat (you can do this with the command @command{eat-reload}).
Or alternatively you can set the user options before Eat is loaded.

@anchor{Char Mode}
@cindex char mode
@cindex mode, char
@cindex keybindings, char mode
@cindex keybinding mode, char
@cindex input mode, char
@section Char Mode

By default, Eat is in ``semi-char mode''.  In this input mode, Eat
forwards all supported keys to terminals, except some exceptions,
@pxref{Semi-char Mode}.  It is possible to input them with @kbd{C-q},
but it is not very convenient.

@kindex C-c M-d @r{(``semi-char mode'')}
To overcome this problem, Eat implements another input mode called
``char mode''.  To switch to ``char mode'', press @kbd{C-c M-d} in
``semi-char mode''.  In Eshell, the command
@command{eshell-toggle-direct-send} is remapped to enable
``char-mode'', which is usually bound to @kbd{C-c M-d}.

In this input mode, Eat forwards all supported keys.  However, input
methods still work in this mode, so you can still input keys that are
not on your keyboard.

@kindex C-M-m @r{(``char mode'')}
@kindex M-RET @r{(``char mode'')}
To get out of ``char mode'', press @kbd{C-M-m} or @kbd{M-@key{RET}},
this switches back to ``semi-char mode''.

@anchor{Emacs Mode}
@cindex emacs mode
@cindex mode, emacs
@cindex keybindings, emacs mode
@cindex keybinding mode, emacs
@cindex input mode, emacs
@section Emacs Mode

In ``emacs mode'', no input events are send to the terminal.  In this
mode, you can interact with the terminal buffer just like a regular
buffer.  However, you are not allowed to change the buffer contents.

@kindex C-c C-e @r{(``semi-char mode'')}
To switch to ``emacs mode'', press @kbd{C-c C-e} from ``semi-char
mode''.

@kindex C-c C-k @r{(``emacs mode'')}
In this mode, @kbd{C-c C-k} kills the terminal program like in
``semi-char mode''.

@kindex C-c C-j @r{(``emacs mode'')}
@kindex C-c M-d @r{(``emacs mode'')}
From ``emacs mode'', you can switch to ``semi-char mode'' with
@kbd{C-c C-j} and to ``char mode'' with @kbd{C-c M-d}.  In Eshell, the
command @command{eshell-toggle-direct-send} is remapped to enable
``char-mode'', which is usually bound to @kbd{C-c M-d}.

@anchor{Line Mode}
@cindex line mode
@cindex mode, line
@cindex keybindings, line mode
@cindex keybinding mode, line
@cindex input mode, line
@section Line Mode

In ``line mode'', input is sent one line at a line, similar to Comint
or Shell mode (@pxref{Interactive Shell,,, emacs, GNU Emacs Manual}).
Like ``emacs mode'', you can interact with buffer as you wish; but at
the very end of the buffer, you can edit the input line with usual
Emacs commands.  This is not available in Eshell.

@kindex C-c C-l @r{(``semi-char mode'')}
@kindex C-c C-l @r{(``emacs mode'')}
To enter ``line mode'', press @kbd{C-c C-l} from ``semi-char mode'' or
``emacs mode''.

@kindex @key{RET} @r{(``line mode'')}
@kindex C-c @key{SPC} @r{(``line mode'')}
@kbd{@key{RET}} sends the current input with a trailing newline, and
clear the input area for new input to be written.  When called with a
prefix argument, no newline is appended before sending input.  To
input a newline character without actually sending it, you can press
@kbd{C-c @key{SPC}}.

@kindex C-c C-c @r{(``line mode'')}
@kindex C-d @r{(``line mode'')}
@kbd{C-c C-c} discards the input completely and sends an interrupt to
the terminal.  @kbd{C-d} deletes the character after the point, or
sends EOF if the input is empty.

@vindex eat-line-auto-move-to-input
You can't modify the terminal in ``line mode'', you can write only in
the input line.  Eat automatically moves the point to the input line
if you try to insert character in the terminal region.  This behavior
can be disabled by customizing @code{eat-line-auto-move-to-input} to
@code{nil}.

@kindex C-c C-e @r{(``line mode'')}
@kindex C-c C-j @r{(``line mode'')}
@kindex C-c M-d @r{(``line mode'')}
You can exit to ``emacs mode'', ``semi-char mode'' or ``char mode''
with @kbd{C-c C-e}, @kbd{C-c C-j} or @kbd{C-c M-d} respectively.  If
there's any pending input when exiting line mode, it is sent as is to
the terminal.

@kindex M-p @r{(``line mode'')}
@kindex M-n @r{(``line mode'')}
@kindex C-@key{up} @r{(``line mode'')}
@kindex C-@key{down} @r{(``line mode'')}
@kindex M-r @r{(``line mode'')}
@kindex C-c M-r @r{(``line mode'')}
@kindex C-c M-s @r{(``line mode'')}
@kindex C-c C-r @r{(``line mode'')}
@kindex @key{TAB} @r{(``line mode'')}
The input history is recorded.  You can cycle through the history with
@kbd{M-p} and @kbd{M-n}, and also with @kbd{C-@key{up}} and
@kbd{C-@key{down}}.  @kbd{C-c M-r} and @kbd{C-c M-s} searches the
input history taking the current input as the query.  @kbd{C-c M-r}
searches backward while @kbd{C-c M-s} searches forward.  And @kbd{C-c
C-r} searches the input history using minibuffer with completion,
useful specially if you use any minibuffer completion UI/framework.

You can also use Isearch
(@pxref{Incremental Search,,, emacs, GNU Emacs Manual}) to search
through the input history, with @kbd{M-r}.  You can also customize
@code{eat-line-input-history-isearch} to use all standard Isearch
commands to search the input history.

@vindex eat-line-input-history-isearch
@defopt eat-line-input-history-isearch
Controls where Isearch searches in Eat buffer.  If @code{t}, usual
Isearch commands in Eat buffer search in the input history.  If
@code{dwim}, Isearch keys search in the input history only when
initial point position is on input line.  When starting Isearch from
other parts of the Eat buffer, they search in the Eat buffer.  If
@code{nil}, Isearch operates on the whole Eat buffer.
@end defopt

Input history is not loaded from the shell history file, to do that,
@xref{Line Mode Integration}.

@node Password Input
@cindex password input
@cindex credential input
@cindex input, password
@cindex input, credential
@chapter Password Input

By default, every keystroke gets recorded in the lossage, which can be
seen by pressing @kbd{C-h l}.  This is actually a good thing, unless
you're inputting password.

@findex eat-send-password
Emacs doesn't record keystrokes when a password is read from the
minibuffer.  However, when the password prompt is in the terminal, the
keys you use to type in your password gets recorded.  To prevent this
from happening, you can use the command @command{eat-send-password},
it'll read password from the minibuffer and send it.  Since the
password is read from the minibuffer, it's not recorded.

@part Part III:@* Advanced Customizations

@node Shell Integration
@cindex shell integration
@cindex integration, shell
@chapter Shell Integration

Eat comes with shell scripts to integrate your favorite shell with
Eat.  When shell integration is enabled and the script is loaded in
your shell, it'll take care of everything and provide many useful
features.

Currently only GNU Bash and Zsh are supported.

If you use GNU Bash, put the following in your @samp{.bashrc} file:

@example
[ -n "$EAT_SHELL_INTEGRATION_DIR" ] && \
  source "$EAT_SHELL_INTEGRATION_DIR/bash"
@end example

If you use Zsh, put the following in your @samp{.zshrc} file:

@example
[ -n "$EAT_SHELL_INTEGRATION_DIR" ] && \
  source "$EAT_SHELL_INTEGRATION_DIR/zsh"
@end example

@anchor{Directory tracking}
@cindex directory tracking
@cindex tracking directory
@cindex working directory tracking
@cindex tracking working directory
@cindex cwd tracking
@cindex tracking cwd
@section Directory tracking
After you've setup shell integration, the Eat will track the working
directory of your shell.  That means @command{find-file} will start
from your shell's current working directory.  This also works in
Eshell, but after the program exits, the current working directory is
changed back to the directory from where the program was invoked.

@vindex eat-enable-directory-tracking
@defopt eat-enable-directory-tracking
This controls directory tracking.  When set to non-@code{nil}, Eat
tracks the current working directory of programs.
@end defopt

@anchor{Shell Prompt Navigation}
@cindex shell prompt navigation
@cindex shell navigation, shell prompt
@cindex prompt navigation
@cindex navigation, prompt
@section Shell Prompt Navigation
@kindex C-c C-p @r{(``emacs mode''})
@kindex C-c C-p @r{(``semi-char mode'')}
@findex eat-previous-shell-prompt
@kindex C-c C-n @r{(``emacs mode'')}
@kindex C-c C-n @r{(``semi-char mode'')}
@findex eat-next-shell-prompt
You can navigate shell prompts in ``emacs'' and ``semi-char'' mode.
@kbd{C-c C-p}, bound to @command{eat-previous-shell-prompt}, goes to
the previous shell prompt.  @kbd{C-c C-n}, bound to
@command{eat-next-shell-prompt}, is the opposite, it goes to the next
shell prompt.  This doesn't work in Eshell.

@cindex narrow to shell prompt
@cindex narrow to prompt
@cindex narrow, shell prompt
@cindex narrow, prompt
@kindex C-x n d @r{(``emacs mode'')}
@kindex C-x n d @r{(``semi-char mode'')}
@findex eat-narrow-to-shell-prompt
You can narrow (@pxref{Narrowing,,, emacs, GNU Emacs Manual}) down Eat
buffer to a shell prompt and its output (if any) using the key
sequence @kbd{C-x n d}, bound to @command{eat-narrow-to-shell-prompt}.

@anchor{Shell Prompt Annotation}
@cindex shell prompt annotation
@cindex annotation, shell prompt
@cindex annotate, shell prompt
@cindex prompt annotation
@cindex annotation, prompt
@cindex annotate, prompt
@section Shell Prompt Annotation
When shell integration is setup, Eat annotates each shell prompt.  Eat
puts a mark on the shell prompt indicating the whether the command
entered in that prompt is running, exited successfully or exited with
non-zero status.  This doesn't work in Eshell.  You can disable this
feature if you want.

@vindex eat-enable-shell-prompt-annotation
@defopt eat-enable-shell-prompt-annotation
This controls shell prompt annotation by Eat.  When set to
non-@code{nil}, Eat annotates shell prompts to indicate the status of
the command entered in that prompt.
@end defopt

Eat uses the marginal area
(@pxref{Display Margins,,, elisp, GNU Emacs Lisp Reference Manual}) on
the left side to display the annotation.  You also use the right
margin.

@vindex eat-shell-prompt-annotation-position
@defopt eat-shell-prompt-annotation-position
This controls where the shell prompt annotations are displayed.  When
set to @code{left-margin} (the default), Eat uses the left margin.
When set to @code{right-margin}, Eat uses the right margin.
@end defopt

@vindex eat-shell-prompt-annotation-running-margin-indicator
@vindex eat-shell-prompt-annotation-running
@vindex eat-shell-prompt-annotation-success-margin-indicator
@vindex eat-shell-prompt-annotation-success
@vindex eat-shell-prompt-annotation-failure-margin-indicator
@vindex eat-shell-prompt-annotation-failure
Eat uses the strings ``-'', ``0'' and ``X'' respectively to indicate
the command is running, the command has succeeded and the command has
failed.  You can also customize the them. The user option
@code{eat-shell-prompt-annotation-running-margin-indicator} and the
face @code{eat-shell-prompt-annotation-running} control the indicator
used to indicate the command is running.  The user option
@code{eat-shell-prompt-annotation-success-margin-indicator} and the
face @code{eat-shell-prompt-annotation-success} control the indicator
used to indicate the command has exited successfully.  And finally
the user option
@code{eat-shell-prompt-annotation-failure-margin-indicator} and the
face @code{eat-shell-prompt-annotation-failure} control the indicator
used to indicate the command has exited unsuccessfully with non-zero
exit status.

@anchor{Message Passing}
@section Message Passing

After enabling shell integration, you can send messages to Emacs from
your shell.  Then you can handle the message on Emacs side using usual
Emacs Lisp function.

When shell integration script is loaded, a function named
@command{_eat_msg} is defined in your shell.  You can use this to send
any message to Emacs.  (The @samp{_} in the beginning of the function
name is intentional to prevent shadowing any actual command.)

@deffn Command _eat_msg @var{handler-name} @var{message}...
Send message @var{message}, handled by the handler named
@var{handler-name} in Emacs.
@end deffn

The messages are handled with the handlers defined in
@code{eat-message-handler-alist}.

@vindex eat-message-handler-alist
@defopt eat-message-handler-alist
Alist of message handler name and its handler function.  The keys are
the names of message handlers (i.e. the @var{handler-name} argument of
@command{_eat_msg}), and the values are their respective handler
functions.  The handler function is called with the @var{message}
arguments of @command{_eat_msg}.  Messages with undefined handlers are
ignored.  To disable message passing, set this to nil.
@end defopt

Beware, messages can be sent by malicious and/or buggy programs
running in the shell, therefore you should always verify the message
before doing anywhere.

@anchor{Line Mode Integration}
@cindex line mode integration
@cindex line mode shell integration
@cindex integration, shell, line mode
@section Line Mode Integration

When shell integration is enabled, the input history of line mode is
automatically filled with the shell history when the shell starts.
Also you can make Eat automatically switch to ``line mode''
(@pxref{Line Mode}) for you when the shell prompt appears.

@vindex eat-enable-auto-line-mode
@defopt eat-enable-auto-line-mode
When non-nil, automatically switch to line mode the shell prompt
appears.
@end defopt

@node Querying Before Kill
@cindex querying before kill
@cindex querying before kill terminal
@cindex confirm before kill
@cindex confirm before kill terminal
@cindex terminal, kill, query
@cindex terminal, kill, confirm
@chapter Querying Before Kill

When a terminal is killed, the terminal process is also killed.  Since
the process can do some important things, Eat asks for confirmation
before killing a terminal with running process by default.  Eat
provides the user option
@code{eat-query-before-killing-running-terminal} to control this.

@vindex eat-query-before-killing-running-terminal
@defopt eat-query-before-killing-running-terminal
When set to @code{nil}, Eat would never ask.  When set to @code{t},
Eat would always ask for confirmation.  When set to @code{auto}, Eat
would ask only if a shell command is running inside the shell running
in the terminal.  This is effective only after shell integration is
enabled in the shell (@pxref{Shell Integration}) (i.e. after the shell
integration code is executed on shell); before that it is essentially
same as @code{t}, and Eat will always query.
@end defopt

@node Changing Shell
@cindex changing default shell
@cindex changing shell
@cindex shell, default, changing
@cindex default, shell changing
@cindex shell, changing shell
@chapter Changing the Default Shell

Eat automatically uses a reasonable shell by default.  However you can
customize it.

@vindex eat-shell
@defopt eat-shell
The default shell to run.
@end defopt

@vindex eat-tramp-shells
@defopt eat-tramp-shells
This user options allows you to customize default shell for each Tramp
method.  It's an alist and it's elements are of form (TRAMP-METHOD
SHELL).
@end defopt

@vindex eat-default-shell-function
@defopt eat-default-shell-function
This user options gives more control on the default shell.  It
specifies a function to call without any argument, whose return value
is used as the default shell.

If you change this from the default value, @code{eat-shell} and
@code{eat-tramp-shells} won't work.
@end defopt

@node Display
@cindex display
@chapter Display

Display is the region you see on the terminal.  The program writes to
the display and manipulates the text on the display.  The display can
be of any size.  The cursor is always on the display (though it might
be invisible sometimes, @pxref{Cursor Types}).

@vindex window-adjust-process-window-size-function
You can resize the display by resizing the terminal window.  The
display size is controlled by the Emacs user option
@code{window-adjust-process-window-size-function}. @xref{Process
Buffers,,, elisp, GNU Emacs Lisp Reference Manual} for the possible
values of the user option.

@node Scrollback
@cindex scrollback
@chapter Scrollback

When you go too downward on the terminal, the terminal starts to
``scroll''.  This causes the line at the upper side of the terminal to
go out of the display and become hidden.  But these line are not
deleted, they are just put in the scrollback region.

Scrollback region is a region just above the display of the terminal.
This contains the lines that went out of display due to scrolling up.

Scrollback region is not unlimited by default, to avoid using too much
memory.  You can change the limit, or remove it altogether.

@vindex eat-term-scrollback-size
@defopt eat-term-scrollback-size
This controls the size of scrollback region.  It is expressed in
character.  If set to @var{size}, Eat won't store more than @var{size}
characters in the scrollback region.  If set to @code{nil}, the
scrollback region is unlimited.
@end defopt

@node Cursor Types
@cindex cursor types
@cindex types, cursor
@cindex changing cursor
@cindex customizing cursor
@cindex cursor blinking
@cindex blinking cursor
@chapter Cursor Types

In terminal, cursor can be of up to three type: ``visible'',
``invisible'' and ``very visible''.  ``Visible'' is the default cursor
type, which is the cursor you usually see in a shell (unless the shell
changes the cursor type).  ``Invisible'' is, as the name suggests,
invisible, you can't see it.  ``Very visible'' cursor is a blinking
cursor, programs use this to help you not lose the cursor.

The cursor type can customized with three user options for the three
types of cursor.  Each of the user options share the same format.

@vindex eat-default-cursor-type
@defopt eat-default-cursor-type
This controls the cursor shape of the ``visible'' cursor type.
@end defopt

@vindex eat-invisible-cursor-type
@defopt eat-invisible-cursor-type
This controls the cursor shape of the ``invisible'' cursor type.
@end defopt

@vindex eat-very-visible-cursor-type
@defopt eat-very-visible-cursor-type
This controls the cursor shape of the ``very visible'' cursor type.
This cursor blinks, switching between the default cursor shape and a
hollow box.
@end defopt

@vindex eat-vertical-bar-cursor-type
@defopt eat-vertical-bar-cursor-type
This controls the cursor shape of the ``vertical bar'' cursor type.
@end defopt

@vindex eat-very-visible-vertical-bar-cursor-type
@defopt eat-very-visible-vertical-bar-cursor-type
This controls the cursor shape of the ``very visible vertical bar''
cursor type.  This cursor blinks.
@end defopt

@vindex eat-horizontal-bar-cursor-type
@defopt eat-horizontal-bar-cursor-type
This controls the cursor shape of the ``horizontal bar'' cursor type.
@end defopt

@vindex eat-very-visible-horizontal-bar-cursor-type
@defopt eat-very-visible-horizontal-bar-cursor-type
This controls the cursor shape of the ``very visible horizontal bar''
cursor type.  This cursor blinks.
@end defopt

The value type of all these user options is a list.  The list is of
form (@var{cursor-on} @var{blinking-frequency} @var{cursor-off}).
@var{blinking-frequency} is the frequency of blinking of cursor.  It
is a number, controlling how many times the cursor will blink a
second.  This can also be @code{nil}, this will disable cursor
blinking.  @var{cursor-on} is the default cursor shape, only this
shape is shown on the display when blinking is disabled.  This uses
the same format as Emacs's @code{cursor-type} user option
(@pxref{Cursor Display,,, emacs, GNU Emacs Manual}).  When
@var{blinking-frequency} is a number, Eat will consult to the third
element of the list, @var{cursor-off}, whose format same as
@var{cursor-on}.  The blinking cursor switches between @var{cursor-on}
and @var{cursor-off} cursor shape.

@node Mouse Tracking
@cindex mouse tracking
@cindex tracking mouse
@chapter Mouse Tracking

Eat tracks mouse by default, when the program supports mouse.  But
sometimes, you may want to avoid using mouse, or you might not have a
mouse at all.  So mouse tracking can be toggled.

@vindex eat-enable-mouse
@defopt eat-enable-mouse
This user option controls mouse tracking.  When set to non-@code{nil},
mouse tracking is enabled.  Set to this to @code{nil} to disable mouse
tracking.  This is enabled by default.
@end defopt

@node Clipboard
@cindex clipboard
@chapter Clipboard

@cindex yanking
@findex eat-yank
@kindex C-y @r{(``semi-char mode'')}
@findex eat-yank-pop
@kindex M-y @r{(``semi-char mode'')}
Just like any other buffer, you can yank text in terminal with
@kbd{C-y} (bound to @command{eat-yank}) or @kbd{M-y} (bound to
@command{eat-yank-pop}) in ``semi-char mode''.

@cindex clipboard integration
Programs can also request to the terminal to kill (@pxref{Killing,,,
emacs, GNU Emacs Manual}) something.  It is up to Eat whether the
request will be fulfilled or not.  By default, Eat fulfills the
request and kills the text.  This can sometimes be annoying, when the
program automatically kills text without user interaction.  This
killing can be configured with the following user option:

@vindex eat-enable-kill-from-terminal
@defopt eat-enable-kill-from-terminal
This controls killing texts from terminal.  When set to
non-@code{nil}, killing something from terminal add the text to
Emacs's kill ring (@pxref{Kill Ring,,, emacs, GNU Emacs Manual}).
This is enabled by default.
@end defopt

Programs can also request the text in kill ring.  Again, this is up to
Eat whether the request will be fulfilled or not.  You can customize
the following user option to configure this:

@vindex eat-enable-yank-to-terminal
@defopt eat-enable-yank-to-terminal
This controls sending kill ring texts to terminal.  When set to
non-@code{nil}, programs can receive the kill ring contents.  This is
disabled by default for security reasons.
@end defopt

@node Colors
@cindex colors
@cindex customizing colors
@chapter Colors

Eat can show more than 16 million colors (16,777,216 colors exactly).
Eat has also a palette of 256 colors, which is more than enough for
most applications.  Programs usually use this color palette.  Each of
these 256 colors can customized.

There are 256 faces for the 256 colors, one face for each color.  They
are named like @code{eat-term-color-@var{n}}, which corresponds to
color @var{n}, and @var{n} can be any number between 0 and 255
(inclusive).  For example, color 42 is can be changed by customizing
@code{eat-term-color-42}.

The foreground attribute contains the color value to use for the
corresponding color.  Other attributes are currently ignored and
reserved for future changes.

@cindex color aliases
@cindex face aliases
@cindex aliases, face
@cindex aliases, color
Each of the first 16 colors, from @code{eat-term-color-0} to
@code{eat-term-color-15} also have a alias.  They are respectively
@code{eat-term-color-black},
@code{eat-term-color-red},
@code{eat-term-color-green},
@code{eat-term-color-yellow},
@code{eat-term-color-blue},
@code{eat-term-color-magenta},
@code{eat-term-color-cyan},
@code{eat-term-color-white},
@code{eat-term-color-bright-black},
@code{eat-term-color-bright-red},
@code{eat-term-color-bright-green},
@code{eat-term-color-bright-yellow},
@code{eat-term-color-bright-blue},
@code{eat-term-color-bright-magenta},
@code{eat-term-color-bright-cyan}
and @code{eat-term-color-bright-white}.

Eat also supports 24-bit colors, or so called ``truecolor''.  Programs
like Emacs can give a RGB triplet to use as the color of some text.
As the programs directly specify the color in this case, you can't
customize these color.  But you may configure the program sending the
color codes.

@cindex color advertisement
@cindex advertising colors
Eat doesn't always advertise color support depending on the display
Eat is running.  For example, if you are on a Linux console which
supports only eight colors, Eat will advertise eight color support to
the programs, while on graphical displays with 24-bit color support,
Eat will report 24-bit color support.  This is because Eat supports
more colors, the display doesn't always support them.

@vindex TERM
@cindex @env{TERM} environment variable
@cindex environment variable, @env{TERM}
Eat does the trick by setting the @env{TERM} environment variable of
the program.  The value of @env{TERM} depends on the number of the
available colors on the display.  This environment variable is
controlled by the following user option:

@vindex eat-term-name
@defopt eat-term-name
The value of @env{TERM} environment variable as a string.  The value
can also be a function taking no arguments, that function should
return a string which used as the value of @env{TERM}.  The default
value is @code{eat-term-get-suitable-term-name}, which is responsible
for the behavior described above.
@end defopt

@node Fonts
@cindex fonts
@chapter Fonts

Programs may request the terminal to change the text font.  It can
change text weight, use italic text, or even change the font family
altogether.

@cindex bold text
@cindex text, bold
@vindex eat-term-bold
Programs may request the terminal to show some text bolder than
normal.  Bold text uses the face @code{eat-term-bold}.

@cindex faint text
@cindex text, faint
@vindex eat-term-bold
Programs may also request the terminal to show some text fainter than
normal.  Faint text uses the face @code{eat-term-faint}.

@cindex italic text
@cindex slant text
@cindex text, italic
@cindex text, slant
@vindex eat-term-italic
Programs may request the terminal to show italic text too.  Italic
text uses the customizable face @code{eat-term-italic}.

@cindex font family
@cindex text, font family
The number of available fonts is ten.  Most of the programs doesn't
change the font.  Following many other terminal emulator, Eat actually
uses the same font, the default font, regardless of the font requested
by the program, by default.

@cindex customizing font families
There are ten faces for ten fonts, one face for each.  They are named
like @code{eat-term-font-@var{n}}, which corresponds to color @var{n},
and @var{n} can be any number between 0 and 9 (inclusive).  For
example, the font 6 is can be changed by customizing
@code{eat-term-font-6}.  Font 0 is the default font.

@node Sixel
@cindex sixel
@chapter Sixel

Eat can show Sixel graphics.  Sixel is a bitmap graphics format that
can be used to display graphics in a terminal, for example, images, or
plotting graphs.

You can control the display of Sixel images by customizing the
following user options.

@vindex eat-sixel-scale
@defopt eat-sixel-scale
This is a non-negative number that specifies the amount to scale the
image by.
@end defopt

@vindex eat-sixel-aspect-ratio
@defopt eat-sixel-aspect-ratio
This is a non-negative number that specifies the aspect ratio, i.e.
the ratio of width and height of a Sixel pixel.  For example, the
value of 2 means the width of a Sixel pixel is the double of its
height.
@end defopt

Eat converts Sixel graphics to an image format Emacs can natively
display.  This preference of image formats can be configured by
customizing the @code{eat-sixel-render-formats} user option.

@vindex eat-sixel-render-formats
@defopt eat-sixel-render-formats
List of formats to render Sixel, in order of preference.  Each element
of the list is one of @code{xpm}, @code{svg}, @code{half-block},
@code{background}, @code{none}.  @code{xpm} and @code{svg} means to
use XPM and SVG image format respectively, @code{half-block} means to
use UTF-8 half block characters, @code{background} means to just use
background color, and @code{none} means to not render the image,
instead just clear the area.
@end defopt

@node Blinking Text
@cindex blinking text
@cindex text, blinking
@chapter Blinking Text

Programs can request the terminal to blink some text.  This helps to
get user attention.  But however, often this annoying to many people
and also has accessiblity problems.  So this is disabled by default.

@vindex eat-enable-blinking-text
@defopt eat-enable-blinking-text
This controls the blinking of text with blink attribute.  When set to
non-@code{nil}, Eat arranges that text with blink attribute will
blink at a certain interval.
@end defopt

@findex eat-blink-mode
You can toggle blinking temporarily by toggle the buffer-local minor
mode @command{eat-blink-mode}.  This is only effective in the buffer
where the mode is toggled.

By default, @code{eat-enable-blinking-text} is set to @code{nil}.
This disables text blinking and causes the text with blink attribute
to be displayed in inverse video (swapped foreground and background).

@vindex eat-term-slow-blink
@vindex eat-term-fast-blink
Programs may also request to blink some text more rapidly that other
blinking text.  When blinking is disabled, the face
@code{eat-term-slow-blink} is used for slowly blinking text, and
@code{eat-term-fast-blink} for rapidly blinking text.

When blinking is enabled, by setting @code{eat-enable-blinking-text}
to non-@code{nil} value, the following user options can be customized
to change the rate of blinking:

@vindex eat-slow-blink-frequency
@defopt eat-slow-blink-frequency
The blinking rate of slowly blinking text.  When set to a number N,
it causes slowly blinking text to blink N times a second.  The value
can also be a floating point number.  The default value is 2, meaning
that the slowing text will blink two times a second.
@end defopt

@vindex eat-fast-blink-frequency
@defopt eat-fast-blink-frequency
The blinking rate of rapidly blinking text.  When set to a number N,
it causes rapidly blinking text to blink N times a second.  The value
can also be a floating point number as well.  The default value is 3,
meaning that the slowing text will blink three times a second.
@end defopt

@node Performance Tuning
@cindex performance tuning
@cindex tuning performance
@chapter Performance Tuning

Eat tries to be as fast as possible.  So Eat employs some techniques
to maximize performance.

Some program choke and hang when given too much input at once.  So Eat
divides large input to smaller chunks and sends the chunks one at a
time.  The maximum size of a input chunk is controlled by
@code{eat-input-chunk-size}.

@vindex eat-input-chunk-size
@defopt eat-input-chunk-size
The value is a integer.  Eat treat input larger than this many
character as large and breaks it into chunks of at most this size
before sending the input.
@end defopt

@cindex flickering
@cindex reason behind flickering
@cindex cause of flickering
Programs also break large output into smaller chunks before sending
it to the terminal, for same reason.  Eat doesn't suffer from the
problem, but there isn't any standard way to inform programs about
this, and usually there are other obstructions sending large amount of
data at once.  These small chunks create another problem for Eat,
flickering.  When updating the whole display, the output is usually
pretty large and the programs break them into smaller chunks.  Each of
the chunks update the display partially.  After receiving the last
chunk, the update is complete and the display can be updated.  But it
is impossible for Eat to guess the last chunk, so Eat has to redisplay
or update the display after receiving each chunk.  This is the reason
why sometimes the terminal shows some old contents and some new.  This
only lasts for a fraction of a second until the next chunk is received
and processed.  This is flickering.  This also degrades performance,
because redisplay is an expensive process and takes some time.

@cindex fixing flickering
@cindex flickering fix
@cindex latency
Fixing the flickering completely is not possible.  Eat tries to
decrease flickering by deferring redisplay.  After receiving a chunk,
Eat waits for a tiny fraction of a second.  If another chunk arrives
within the time, the redisplay is postponed.  Then Eat waits for the
same amount of time and this goes on.  When timeout occurs, Eat
processing the output and displays the output.  This causes a small
latency between output arrive and redisplay, but this is usually not
long enough for human eyes to catch it.  This waiting time can be
configured with the following user option:

@vindex eat-minimum-latency
@defopt eat-minimum-latency
The value is the time in seconds to wait for the next chunk to arrive.
This is the minimum latency between the first chunk after a redisplay
and the next redisplay.  For example, if you press @kbd{@key{RET}} in
an empty Bash prompt, the next prompt won't appear before this much
time.

You should set the time to something comfortable for you.  You can
also set this to zero to disable waiting and showing the output
instantly, but this would likely cause a lot of flickering.
@end defopt

However, this waiting raises another problem.  What if you execute the
POSIX command @samp{yes} in the terminal?  It will write infinite
``y''s in the terminal without any delay between them anywhere.  Eat
will wait indefinitely for a delay between two chunks, which will
never happen, unless the program is executed remotely and the
connection is slow enough.  So Eat has a limit for waiting, the
display will be always be updated after this time.  This limit also
customizable:

@vindex eat-maximum-latency
@defopt eat-maximum-latency
The value is the time in seconds to wait at most for chunk.  In case
of large burst of output, redisplay is never deferred more than this
many seconds, and cause a latency of up to this many seconds.

You should set the time to something comfortable for you.  You can
also set this to zero to disable waiting and showing the output
instantly, but this would likely cause a lot of flickering.
@end defopt

Due to some limitations, shell prompt annotations
(@pxref{Shell Integration}) can get messed up sometimes.  Eat
automatically corrects them after each terminal redisplay.  However,
this can have some performance impact when the terminal scrollback and
display is large enough (unless the buffer is narrowed).  So Eat
defers the correction.

@vindex eat-shell-prompt-annotation-delay
@defopt eat-shell-prompt-annotation-delay
The value is the time in seconds to wait for more output before
correcting shell prompt annotations.

You should set the time to something comfortable for you.  You can
also set this to zero to disable waiting and correct annotations
instantly, but this may cause the terminal to slow down in some cases.
@end defopt

The user options described in this chapter have reasonable default
values, but the default values may change anytime.

@part Part IV:@* Recovering from Problems

@node Common Problems
@cindex common problems
@cindex problem, common
@chapter Common Problems

This chapter describe how to recognize and handle situations in which
Eat does something unexpected, such as hangs, garbled text, etc.

@menu
* Not Recognized::      The program can't recognize Eat.
* Garbled Text::        When you get garbage on your terminal.
* Input Invisible::     The input is not shown.
* Not Responding::      What to do if Eat is unresponsive.
* Signaled an Error::   The worst and the most unlikely bug.
* Bugs in Manual::      What if there are problems in this manual?
@end menu

@node Not Recognized
@cindex not recognized
@cindex problem, not recognized
@cindex terminal not recognized
@cindex problem, terminal not recognized
@section Terminal Not Recognized

If your program says that it can't recognize the terminal, probably
the @env{TERM} environment variable has a wrong value.

@vindex eat-term-name
Check the value of @env{TERM}, if it's not set to something like
@samp{eat-...}, check the user option @code{eat-term-name}.  If that's
correct that your shell might be changing the @env{TERM} environment
variable.  If @code{eat-term-name} isn't correct, customize to a
suitable value and try again, your problem should be fixed.

@vindex eat-term-terminfo-directory
If @env{TERM} has the correct value, then probably the Terminfo
databases of Eat are missing.  This can happen if you have installed
Eat without using the package from NonGNU ELPA
(@pxref{Packages,,, emacs, GNU Emacs Manual}).  Check that whether
the values of the environment variable @env{TERMINFO} and the user
option @code{eat-term-terminfo-directory} match.  If they match,
customize @code{eat-term-terminfo-directory} to the directory
containing the Terminfo databases, the program should now recognize
Eat.  If they don't match, then your shell is probably responsible for
the problem.

@findex eat-compile-terminfo
If the program is not recognizing the terminal even when
the correct directory is set as @code{eat-term-terminfo-directory},
probably the precompiled Terminfo databases aren't working properly on
your system.  You can invoke the command
@command{eat-compile-terminfo} to recompile it for your system.

If you can't find the directory containing Terminfo databases, you can
compile it yourself.  First, set @code{eat-term-terminfo-directory} to
the directory where to put the Terminfo databases.  Then invoke the
command @command{eat-compile-terminfo} to compile the Terminfo
databases.

@node Garbled Text
@cindex garbled text
@cindex problem, garbled text
@cindex problem, text garbled
@section Garbled Text on Terminal

If the text on the terminal looks wrong, first check out the value of
@env{TERM}.  Usually @env{TERM} has a wrong value set, making programs
send invalid escape sequences.

First, @pxref{Not Recognized}; the problem is most likely because the
program doesn't recognize Eat, and it stays silent instead of
reporting that.

If the problem isn't resolved after following the instructions in the
previous section, probably the precompiled Terminfo databases aren't
working properly on your system.  Running the command
@command{eat-compile-terminfo} will recompile it for your system.

If the problem still persists, may be your program is blindly assuming
that the terminal is XTerm-compatible.  If so, what you are seeing is
the current state of ``XTerm-compliance''.  Though it's not really a
bug, we really want to know what's problem so that we can fix it and
improve XTerm-compliance.  @xref{Reporting Bugs} for instructions on
sending bug reports or feature request.

The other potential reason is that Eat is not working.  This is
definitely a bug, so please report it.

@node Input Invisible
@cindex input invisible
@cindex input, invisible
@cindex invisible input
@cindex invisible, input
@section Input Invisible

This can happen if the @samp{stty} program is unavailable on the
system.  Eat uses @samp{stty} to set various terminal settings
including input echoing.  Please install the @samp{stty} program to
fix the problem.

@vindex eat-eshell-fallback-if-stty-not-available
If you are using Eat from Eshell (@pxref{Eshell Terminal}), you might
want to set @code{eat-eshell-fallback-if-stty-not-available} to handle
such cases.  The user option can be set to three possible value,
@code{t} to automatically fallback to bare Eshell when @samp{stty} is
not available, @code{nil} to do nothing, and @samp{ask} to ask
interactively.

@node Not Responding
@cindex not responding, eat
@cindex not responding, emacs
@cindex eat not responding
@cindex emacs not responding
@cindex problem, eat not responding
@cindex problem, emacs not responding
@cindex problem, not responding, eat
@cindex problem, not responding, emacs
@section Emacs or Eat Not Responding

If you run something that outputs huge amount of data, your Emacs may
not respond, and even quitting may not work.  Quitting doesn't work
while doing something terminal related (output processing, for
example), and that's intentional, because quitting would mess up the
terminal.

The best way to fix it is to stop the program, so that Eat is not
overloaded.  To avoid the problem in future, it is recommended to run
those programs in faster terminals like bare Eshell (i.e. without
Eat-Eshell), Comint, or external terminal emulators.

@node Signaled an Error
@cindex signaled an error
@cindex eat signaled an error
@cindex problem, signaled an error
@cindex problem, eat signaled an error
@section Eat Signaled an Error

The worst thing that happen is that Eat might signal an error.  It is
the worst thing possible, because it messes up the terminal, and also
a security hole.  Fortunately, this is very rare.  If you ever find
any such bug, you should report the bug (@pxref{Reporting Bugs}) as
soon as possible with as much information as possible.

@findex eat-reset
Once the error signaled, your best option is to delete the terminal
and start a new one.  But if you don't want to delete the terminal,
you can try invoking the command @command{reset} from your shell.  If
for some reason you can't do that, invoke the Emacs command
@command{eat-reset}.  This will reset most of the terminal state and
give you a clean terminal to work with.  However, it mayn't work if
you're really unlucky, in that case deleting the terminal and starting
a new one is your only option.

@node Bugs in Manual
@cindex bugs in manual
@cindex typos in manual
@cindex bugs, manual
@cindex typos, manual
@cindex manual, bugs
@cindex manual, typos
@cindex problems, bugs in manual
@cindex problems, typos in manual
@cindex problems, bugs, manual
@cindex problems, typos, manual
@cindex problems, manual, bugs
@cindex problems, manual, typos
@section Bugs in Manual

Human makes mistake, and we are no exceptions.  But we are trying hard
to improve Eat and it's manual.

If you don't understand something even after a careful rereading,
that's a bug.

If you find anything unclear in this manual, that's a bug.

This manual's job is make everything clear, so failing to do that
indicates a bug.

If the built-in documentation and this manual don't agree, one of them
must be wrong, and that's a bug.

If you Eat doesn't behave as this manual describes, that's a bug.

If you find any typing mistakes, that's a bug.

If you find a bug, please report it.  @xref{Reporting Bugs} for
instruction on how to report it.

@node Reporting Bugs
@cindex reporting bugs
@cindex bug reporting
@cindex problem, reporting
@chapter Reporting Bugs

We welcome bug reports and feature request.  If you think you have
found a bug, please report it.  If you're doubt, please send it
anyway.  We can't promise that we'll fix the bug or implement your
feature idea, or always agree that it's a bug, but we always want to
hear from you.  Please report bugs at
@url{https://codeberg.org/akib/emacs-eat/issues/}.  You may send the
bug report by emailing to the maintainer
(@kbd{M-x describe-package @key{RET} eat @key{RET}} would show the
email address), but we prefer the former method, since the report is
visible to everyone immediately.

The most important principle in reporting a bug is to report
@emph{facts}.  Hypotheses and verbal descriptions are useful when they
are more guesses, but in no way substitute for detailed raw data.  You
are encouraged to send you finding about bug, but please make sure to
send the raw data needed to reproduce the bug.

For bug reports, please try to reproduce the bug with @samp{emacs -Q}.
This will disable loading your Emacs configuration, ruling out the
potential bugs in your customizations.  Please include enough
information for us to reproduce the bug with @samp{emacs -Q}, so that
we have (or can get) enough information about the bug to fix it.  Some
bugs are hard to reproduce with @samp{emacs -Q}, and some are not
easily reproducible at all, in that case please give us the as much
information as possible about Emacs configuration.  Generally
speaking, enough information includes (but not limited to):

@itemize @bullet
@item
A description of the bug.

@item
The version of Eat you're running.
(@kbd{M-x describe-package RET eat RET} would show the version.)

@item
The version of Emacs you're running.

@item
Your Eat configuration, precisely.

@item
If you didn't or can't reproduce the bug with @code{emacs -Q}, as much
information as possible about Emacs configuration.

@item
Precisely what you did.

@item
Trace output, if you can generate it.  (@xref{Tracing the Terminal}
for instruction to generate it.)

@item
Hardware and operating system names and versions.

@item
Anything else that you think would be helpful.
@end itemize

When in doubt whether to include something or not, please include it.
It is better to include many useless information than to leave out
something useful.

It is critical to send enough information to reproduce the bug.  What
is not critical to ``narrow down'' the example to the smallest
possible -- anything that reproduces the bug will suffice.  (Of
course, if you like doing experiments, the smaller the example, the
better.)

@node Tracing the Terminal
@cindex tracing the terminal
@cindex terminal tracing
@cindex terminal recording
@chapter Tracing the Terminal

When you run into a bug and want to report it, you'll want to trace
the terminal.  Tracing means recording all the terminal activity,
including creation, output, resizing and deleting.

@findex eat-trace-mode
To enable tracing, enable the global minor mode
@command{eat-trace-mode}.  This will trace all new terminals,
including the terminal created inside Eshell.

Trace output for each command will be output in a buffer named
@samp{*eat-trace @var{buffer-name}*: @var{command}}, where
@var{buffer-name} is the buffer showing the terminal, and
@var{command} is the command run in the terminal.

Only the terminals created after the trace mode is enabled are traced.
So if you don't have the mode enabled when you have found a bug,
tracing can't give you any information (as tracing is disabled,
nothing has been recorded).

While submitting bug reports, please include the whole output in the
trace output buffer.  This contains many crucial information required
to reproduce your bug.

@findex eat-trace-replay
You can replay the terminal by executing the command
@command{eat-trace-replay} is the trace output buffer.  You can use
the key @kbd{n} or the key @kbd{@key{down}} to show the next frame.
This is not intended for ordinary users, it's documented here only to
help you debug Eat.  You mustn't rely on the behavior of this
functionality to do anything else.

@part Part V:@* Appendices

@node GNU General Public License
@appendix GNU General Public License

@include gpl.texi

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl.texi

@node Index
@appendix Index

@printindex cp

@bye