From e9010023e6d33ba84dca4b7aea284c9d804b0b8c Mon Sep 17 00:00:00 2001
From: Gregory Heytings <gregory@heytings.org>
Date: Sun, 28 Aug 2022 20:04:11 +0000
Subject: [PATCH] Recommend using fbterm in the Linux console.

* doc/misc/efaq.texi (Emacs in a Linux console): New node.
(Common requests): Entry for the new node.

* etc/PROBLEMS (Linux console problems...): Mention the new FAQ node.
---
 doc/misc/efaq.texi | 65 ++++++++++++++++++++++++++++++++++++++++++++++
 etc/PROBLEMS       |  7 +++++
 2 files changed, 72 insertions(+)

diff --git a/doc/misc/efaq.texi b/doc/misc/efaq.texi
index a3459abd04..5fa8080f4b 100644
--- a/doc/misc/efaq.texi
+++ b/doc/misc/efaq.texi
@@ -1602,6 +1602,7 @@ Common requests
 * Filling paragraphs with a single space::
 * Escape sequences in shell output::
 * Fullscreen mode on MS-Windows::
+* Emacs in a Linux console::
 @end menu
 
 @node Setting up a customization file
@@ -3031,6 +3032,70 @@ Fullscreen mode on MS-Windows
 Emacs frame and then evaluate @code{(frame-height)} and
 @code{(frame-width)} with @kbd{M-:}.
 
+@node Emacs in a Linux console
+@section How can I alleviate the limitations of the Linux console?
+@cindex Console, TTY
+
+If possible, we recommend to run, in a Linux console, Emacs inside
+fbterm.  This brings the Linux console on par with most terminal
+emulators under X.  To do this, install fbterm, for example with the
+package manager of your GNU/Linux distribution, and execute the
+command
+
+@example
+$ fbterm
+@end example
+
+This will create a sample configuration file @file{~/.fbtermrc} in
+your home directory.  Edit that file and change the options
+@code{font-names} and @code{font-size} if necessary.  For the former,
+you can choose one or more of the lines in the output of the following
+command, separated by commas:
+
+@example
+$ fc-list :spacing=mono family | sed 's/ /\\ /g'
+@end example
+
+Now you can start Emacs inside fbterm with the command
+
+@example
+$ fbterm -- emacs
+@end example
+
+You may want to add an alias for that command in your shell
+configuration file.  For example, if you use Bash, you can add the
+following line to @file{~/.bashrc}:
+
+@example
+alias emacs="fbterm -- emacs"
+@end example
+
+@noindent
+or, if you use Emacs both in the Linux console and under X:
+
+@example
+[[ "$(tty)" =~ "/dev/tty" ]] && alias emacs="fbterm -- emacs"
+@end example
+
+The fbterm terminal emulator may use a number of key bindings for its
+own use, some of which conflict with those that Emacs uses.  Execute
+the following two commands as root to ensure that fbterm does not use
+these key bindings:
+
+@example
+# chmod a-s `which fbterm`
+# setcap cap_sys_tty_config=-ep `which fbterm`
+@end example
+
+If you use Emacs as a root user, the above is not enough, because the
+root user has all privileges, and you can use the following command to
+start Emacs inside fbterm as a root user while ensuring that fbterm
+does not use these key bindings:
+
+@example
+# capsh --drop=cap_sys_tty_config -- -c 'fbterm -- emacs'
+@end example
+
 @c ------------------------------------------------------------
 @node Bugs and problems
 @chapter Bugs and problems
diff --git a/etc/PROBLEMS b/etc/PROBLEMS
index 6624f747c8..3816919d3b 100644
--- a/etc/PROBLEMS
+++ b/etc/PROBLEMS
@@ -2267,6 +2267,13 @@ term/xterm.el) for more details.
 
 *** Linux console problems with double-width characters
 
+If possible, we recommended to run, in a Linux console, Emacs inside
+fbterm (see the node "Emacs in a Linux console" in the Emacs FAQ).
+Most Unicode characters should then be displayed correctly.
+
+If that is not possible, the following may be useful to alleviate the
+problem of displaying Unicode characters in a raw console.
+
 The Linux console declares UTF-8 encoding, but supports only a limited
 number of Unicode characters, and can cause Emacs produce corrupted or
 garbled display with some unusual characters and sequences.  Emacs 28
-- 
2.35.1