bug#39733: 26.3; Unclear direct color mode documentation can cause loading delays

[Eli Zaretskii]

> From: Daniel Long Sockwell <daniel@codesections.com>
> Date: Fri, 21 Feb 2020 21:36:05 -0500
> 
> > Emacs can be invoked with a custom definition as shown below
> >>     $ cat terminfo-24bit.src
> >>     
> >>     # Use colon separators.
> >>     xterm-24bit|xterm with 24-bit direct color mode,
> >>       use=xterm-256color,
> >>       setb24=\E[48:2:%p1%{65536}%/%d:%p1%{256}%/%{255}%&%d:%p1%{255}%&%dm,
> >>       setf24=\E[38:2:%p1%{65536}%/%d:%p1%{256}%/%{255}%&%d:%p1%{255}%&%dm,
> >>     # Use semicolon separators.
> >>     xterm-24bits|xterm with 24-bit direct color mode,
> >>       use=xterm-256color,
> >>       setb24=\E[48;2;%p1%{65536}%/%d;%p1%{256}%/%{255}%&%d;%p1%{255}%&%dm,
> >>       setf24=\E[38;2;%p1%{65536}%/%d;%p1%{256}%/%{255}%&%d;%p1%{255}%&%dm,
> >>     
> >>     $ tic -x -o ~/.terminfo terminfo-24bit.src
> >>     
> >>     $ TERM=xterm-24bit emacs -nw
> Source: Emacs FAQ, 5.3
> 
> I followed these directions literally, and enabled direct color support
> in Emacs, apparently without issue.  However, what I did not realize was
> that I ought *not* to have followed the example literally – instead, I
> should have replaced "xterm" with my actual $TERM value.

If the terminfo entry uses xterm-24bits, then you _do_ have to use
xterm-24bit as the value of TERM.  If you want any other terminal, the
terminfo entry should have a different name.  The example shows it for
xterm.

> Months later, I realized that I was experiencing a very odd bug: my
> Emacs instance was taking well over 2 seconds to start in a terminal,
> even when invoked with `emacs -Q -nw`.  Even more oddly, I determined
> `M-x emacs-init-time` showed a very low time – whatever was causing the
> slowdown was outside of the normal init process.  After fairly extensive
> testing, I discovered that the slowdown was caused by a pselect
> timeout.  This one, according to strace:
> 
> > pselect6(5, [4], [], NULL, {tv_sec=1, tv_nsec=998526670}, {NULL, 8}) =
> > 0 (Timeout) <2.000940>
> 
> After even more testing, I determined that the issue was caused by the
> terminfo/$TERM settings: apparently, if the user has a $TERM value that
> does not match their terminal, Emacs will have a 2-second delay before
> launching, waiting for whatever that pselect call is looking for.

That's because for xterm we support additional features, unrelated to
colors, which need to be probed at startup.  The probe sends a special
control sequence to the terminal, and then waits for the response with
a 2 sec timeout.  Your terminal doesn't support those control
sequences, so it seems, so you get the timeout.

> Once I finally figured the above out, I decided to file this bug in the
> hope that the documentation can be updated and other can avoid spending
> as long with this issue as I did.

The latest version of the Emacs FAQ already says at the end of this
section:

     If your terminal is incompatible with XTerm, you may have to use
  another ‘TERM’ definition.  Any terminal whose name includes ‘direct’
  should be a candidate.  The ‘toe’ command can be used to find out which
  of these are installed on your system:

       $ toe | grep '\-direct'

       konsole-direct  konsole with direct-color indexing
       vte-direct      vte with direct-color indexing
       st-direct       st with direct-color indexing
       xterm-direct2   xterm with direct-color indexing (old)
       xterm-direct    xterm with direct-color indexing

     Terminals with ‘RGB’ capability treat pixels #000001 - #000007 as
  indexed colors to maintain backward compatibility with applications that
  are unaware of direct color mode.  Therefore the seven darkest blue
  shades may not be available.  If this is a problem, you can always use
  custom terminal definition with ‘setb24’ and ‘setf24’.

Given this addition, do you see anything else that needs to be changed
in the FAQ?

Thanks.