bpo-42225: IDLE - document two unix-related problems. (#25078)
1. Bad IP masquerade rules can prevent startup.
2. X cannot handle some complex colored chars.
diff --git a/Doc/library/idle.rst b/Doc/library/idle.rst
index 2b9bd4b..6ef1565 100644
--- a/Doc/library/idle.rst
+++ b/Doc/library/idle.rst
@@ -670,8 +670,16 @@
code execution process. A connection must be established whenever the Shell
starts or restarts. (The latter is indicated by a divider line that says
'RESTART'). If the user process fails to connect to the GUI process, it
-displays a ``Tk`` error box with a 'cannot connect' message that directs the
-user here. It then exits.
+usually displays a ``Tk`` error box with a 'cannot connect' message
+that directs the user here. It then exits.
+
+One specific connection failure on Unix systems results from
+misconfigured masquerading rules somewhere in a system's network setup.
+When IDLE is started from a terminal, one will see a message starting
+with ``** Invalid host:``.
+The valid value is ``127.0.0.1 (idlelib.rpc.LOCALHOST)``.
+One can diagnose with ``tcpconnect -irv 127.0.0.1 6543`` in one
+terminal window and ``tcplisten <same args>`` in another.
A common cause of failure is a user-written file with the same name as a
standard library module, such as *random.py* and *tkinter.py*. When such a
@@ -709,6 +717,13 @@
starting it from a console or terminal (``python -m idlelib``) and see if
this results in an error message.
+On Unix-based systems with tcl/tk older than ``8.6.11`` (see
+``About IDLE``) certain characters of certain fonts can cause
+a tk failure with a message to the terminal. This can happen either
+if one starts IDLE to edit a file with such a character or later
+when entering such a character. If one cannot upgrade tcl/tk,
+then re-configure IDLE to use a font that works better.
+
Running user code
^^^^^^^^^^^^^^^^^