Eat Manual
**********

This manual is for Eat (version 0.6.1, 28 March 2023), a terminal emulator for Emacs.

Copyright ©  2022, 2023  Akib Azmain Turja.

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

Part I: Introduction
********************

Introduction
************

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.

Hello Terminal
**************

The terminal can be started with M-x eat.  It would prompt you for the program to run in the terminal, with a reasonable default value already filled in.  You can specify a program path, or a shell command.  After you hit RET, you will see a terminal, and the program you chose will be run within the terminal in the current directory.  You can interact with it.  If you started a shell, you should get a shell prompt and you should be able to write commands and execute them.  Full screen programs like htop, lynx and Emacs will work inside it, just like other any other terminal.

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

If you give it a numeric argument N, for example C-u 42 M-x eat, it'll switch to a terminal in *eat*<N>, *eat*<42> for example, and it'll create a new terminal if that doesn't exist.

Project-local Terminal
**********************

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 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 eat command.

Eshell Terminal Emulation
*************************

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

To enable terminal emulation in Eshell, enable the global minor mode 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 eshell-visual-commands user option to nil, since they'll work in Eshell when eat-eshell-mode is enabled.

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

Part II: Basic Operations
*************************

Keyboard
********

Just like any other text terminal, the primary interaction device with Eat terminal is the keyboard.  Eat forwards all supported keyboard events like a, E, RET, 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: C-\, C-c, C-x, C-g, C-h, C-M-c, C-u, C-q, M-x, M-:, M-! and M-&.

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

For an alternative way to input these exceptional characters, see Char Mode.

Mouse
*****

Eat supports mouse tracking.  That means in programs like Emacs, 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.

See Mouse Tracking to configure mouse tracking.

Input Modes
***********

By default, Eat forwards all supported keys to terminals, except some exceptions.  It is possible to input them with 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 M-x will input 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.

Semi-char Mode
==============

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

To input these exceptions, there is a key C-q.  This reads the next input event and sends that as the input.  For example, the key sequences C-q M-: inputs M-:, C-q C-g inputs C-g.

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

In ``semi-char mode'', C-c C-c sends a C-c, just for convenience, and C-c C-k kills the terminal program.

You can customize the exceptions by customizing the user option eat-semi-char-non-bound-keys, and eat-eshell-semi-char-non-bound-keys for Eshell integration. Both user options contain a list of keys of form [KEY], where KEY is a key not to bind.  KEY mustn't contain meta modifier.  To not bind a key with meta modifier, use a vector of form [?\e KEY], where KEY is the key without meta modifier.

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

Char Mode
=========

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

To overcome this problem, Eat implements another input mode called ``char mode''.  To switch to ``char mode'', press C-c M-d in ``semi-char mode''.  In Eshell, the command eshell-toggle-direct-send is remapped to enable ``char-mode'', which is usually bound to 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.

To get out of ``char mode'', press C-M-m or M-RET, this switches back to ``semi-char mode''.

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.

To switch to ``emacs mode'', press C-c C-e from ``semi-char mode''.

In this mode, C-c C-k kills the terminal program like in ``semi-char mode''.

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

Part III: Advanced Customizations
*********************************

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 is supported.

If you use GNU Bash, put the following in your .bashrc file:

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

After you've setup shell integration, the Eat will track the working directory of your shell.  That means 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.

 -- User Option: eat-enable-directory-tracking
     This controls directory tracking.  When set to non-nil, Eat tracks the current working directory of programs.

You can navigate shell prompts in ``emacs'' and ``semi-char'' mode. C-c C-p, bound to eat-previous-shell-prompt, goes to the previous shell prompt.  C-c C-n, bound to eat-next-shell-prompt, is the opposite, it goes to the next shell prompt.  This doesn't work in Eshell.

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.

 -- User Option: eat-enable-shell-prompt-annotation
     This controls shell prompt annotation by Eat.  When set to non-nil, Eat annotates shell prompts to indicate the status of the command entered in that prompt.

Eat uses the marginal area (see Display Margins (GNU Emacs Manual)) on the left side to display the annotation.  You also use the right margin.

 -- User Option: eat-shell-prompt-annotation-position
     This controls where the shell prompt annotations are displayed.  When set to left-margin (the default), Eat uses the left margin. When set to right-margin, Eat uses the right margin.

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 eat-shell-prompt-annotation-running-margin-indicator and the face eat-shell-prompt-annotation-running control the indicator used to indicate the command is running.  The user option eat-shell-prompt-annotation-success-margin-indicator and the face eat-shell-prompt-annotation-success control the indicator used to indicate the command has exited successfully.  And finally the user option eat-shell-prompt-annotation-failure-margin-indicator and the face eat-shell-prompt-annotation-failure control the indicator used to indicate the command has exited unsuccessfully with non-zero exit status.

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 eat-query-before-killing-running-terminal to control this.

 -- User Option: eat-query-before-killing-running-terminal
     When set to nil, Eat would never ask.  When set to t, Eat would always ask for confirmation.  When set to 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 (see Shell Integration) (i.e. after the shell integration code is executed on shell); before that it is essentially same as t, and Eat will always query.

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, see Cursor Types).

You can resize the display by resizing the terminal window.  The display size is controlled by the Emacs user option window-adjust-process-window-size-function. See Process Buffers (GNU Emacs Lisp Reference Manual) for the possible values of the user option.

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.

 -- User Option: eat-term-scrollback-size
     This controls the size of scrollback region.  It is expressed in character.  If set to SIZE, Eat won't store more than SIZE characters in the scrollback region.  If set to nil, the scrollback region is unlimited.

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.

 -- User Option: eat-default-cursor-type
     This control the cursor shape of ``visible'' cursor type.

 -- User Option: eat-invisible-cursor-type
     This control the cursor shape of ``invisible'' cursor type.

 -- User Option: eat-very-visible-cursor-type
     This control the cursor shape of ``very visible'' cursor type.  This cursor blinks, switching between the default cursor shape and a hollow box.

The value type of these user options is a list.  The list is of form (CURSOR-ON BLINKING-FREQUENCY CURSOR-OFF). 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 nil, this will disable cursor blinking.  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 cursor-type user option (see Cursor Display (GNU Emacs Manual)).  When BLINKING-FREQUENCY is a number, Eat will consult to the third element of the list, CURSOR-OFF, whose format same as CURSOR-ON.  The blinking cursor switches between CURSOR-ON and CURSOR-OFF cursor shape.

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.

 -- User Option: eat-enable-mouse
     This user option controls mouse tracking.  When set to non-nil, mouse tracking is enabled.  Set to this to nil to disable mouse tracking.  This is enabled by default.

Clipboard
*********

Just like any other buffer, you can yank text in terminal with C-y (bound to eat-yank) or M-y (bound to eat-yank-pop) in ``semi-char mode''.

Programs can also request to the terminal to kill (see Killing (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:

 -- User Option: eat-enable-kill-from-terminal
     This controls killing texts from terminal.  When set to non-nil, killing something from terminal add the text to Emacs's kill ring (see Kill Ring (GNU Emacs Manual)). This is enabled by default.

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:

 -- User Option: eat-enable-yank-to-terminal
     This controls sending kill ring texts to terminal.  When set to non-nil, programs can receive the kill ring contents.  This is disabled by default for security reasons.

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 eat-term-color-N, which corresponds to color N, and N can be any number between 0 and 255 (inclusive).  For example, color 42 is can be changed by customizing 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.

Each of the first 16 colors, from eat-term-color-0 to eat-term-color-15 also have a alias.  They are respectively eat-term-color-black, eat-term-color-red, eat-term-color-green, eat-term-color-yellow, eat-term-color-blue, eat-term-color-magenta, eat-term-color-cyan, eat-term-color-white, eat-term-color-bright-black, eat-term-color-bright-red, eat-term-color-bright-green, eat-term-color-bright-yellow, eat-term-color-bright-blue, eat-term-color-bright-magenta, eat-term-color-bright-cyan and 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.

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.

Eat does the trick by setting the TERM environment variable of the program.  The value of TERM depends on the number of the available colors on the display.  This environment variable is controlled by the following user option:

 -- User Option: eat-term-name
     The value of 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 TERM.  The default value is eat-term-get-suitable-term-name, which is responsible for the behavior described above.

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.

Programs may request the terminal to show some text bolder than normal.  Bold text uses the face eat-term-bold.

Programs may also request the terminal to show some text fainter than normal.  Faint text uses the face eat-term-faint.

Programs may request the terminal to show italic text too.  Italic text uses the customizable face eat-term-faint.

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.

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

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.

 -- User Option: eat-enable-blinking-text
     This controls the blinking of text with blink attribute.  When set to non-nil, Eat arranges that text with blink attribute will blink at a certain interval.

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

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

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

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

 -- User Option: 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.

 -- User Option: 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.

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 eat-input-chunk-size.

 -- User Option: 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.

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.

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:

 -- User Option: 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 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.

However, this waiting raises another problem.  What if you execute the POSIX command 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:

 -- User Option: 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.

Due to some limitations, shell prompt annotations (see 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.  So Eat defers the correction.

 -- User Option: 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.

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

Part IV: Recovering from Problems
*********************************

Common Problems
***************

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

Terminal Not Recognized
=======================

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

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

If TERM has the correct value, then probably the Terminfo entries of Eat are missing.  This can happen if you manually install Eat.  Check that whether the values of the environment value TERM and the user option eat-term-terminfo-directory match.  If they match, customize eat-term-terminfo-directory to the directory that contains the Terminfo database, the program should now recognize Eat.  If they don't match, then your shell is probably responsible for the problem.

Garbled Text on Terminal
========================

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

First, see 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, 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 definite want to know what's problem so that we can fix it. See 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.

Input Invisible
===============

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

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

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.

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 (see Reporting Bugs) as soon as possible with as much information as possible.

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 reset from your shell.  If for some reason you can't do that, invoke the Emacs 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.

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.  See Reporting Bugs for instruction on how to report it.

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 https://codeberg.org/akib/emacs-eat/issues/new.  You may send the bug report by emailing to the maintain (M-x describe-package RET eat 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 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 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 emacs -Q, so that we have (or can get) enough information about the bug to fix it.  Some bugs are hard to reproduce with 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):

  * A description of the bug.

  * The version of Eat you're running. (M-x describe-package RET eat RET would show the version.)

  * The version of Emacs you're running.

  * Your Eat configuration, precisely.

  * If you didn't or can't reproduce the bug with emacs -Q, as much information as possible about Emacs configuration.

  * Precisely what you did.

  * Trace output, if you can generate it.  (see Tracing the Terminal for instruction to generate it.)

  * Hardware and operating system names and versions.

  * Anything else that you think would be helpful.

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

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.

To enable tracing, enable the global minor mode 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 *eat-trace BUFFER-NAME*: COMMAND, where BUFFER-NAME is the buffer showing the terminal, and 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.

You can replay the terminal by executing the command eat-trace-replay is the trace output buffer.  You can use the key n or the 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 V: Appendices
******************

GNU General Public License
**************************

     [file gpl.texi not included]

GNU Free Documentation License
******************************

     [file fdl.texi not included]