From 0d558655452a04bd4fd0dcdcb418d03686edafbd Mon Sep 17 00:00:00 2001
From: egnor <egnor@ofb.net>
Date: Wed, 28 Jul 2021 23:41:47 -0700
Subject: [PATCH] more accurately describe editor behavior

---
 docs/glossary.rst            | 10 ++++++++++
 docs/kittens/remote_file.rst |  7 ++++---
 kitty/options/definition.py  | 14 +++++++-------
 3 files changed, 21 insertions(+), 10 deletions(-)

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 118117ac1..4d46bc182 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -52,6 +52,16 @@ Variables that influence kitty behavior
    files. Defaults to :file:`~/.config/kitty`. For full details of the config
    directory lookup mechanism see, :option:`kitty --config`.
 
+.. envvar:: EDITOR
+
+   The terminal editor (such as `vi` or `nano`) for editing config files.
+   Overridden by :envvar:`VISUAL`.
+
+.. envvar:: VISUAL
+
+   The terminal editor (such as `vi` or `nano`) for editing config files.
+   Takes precedence over :envvar:`EDITOR`.
+
 
 .. envvar:: VISUAL
 
diff --git a/docs/kittens/remote_file.rst b/docs/kittens/remote_file.rst
index 3c661a3a6..d7d3e4b30 100644
--- a/docs/kittens/remote_file.rst
+++ b/docs/kittens/remote_file.rst
@@ -17,9 +17,10 @@ Then hold down :kbd:`ctrl+shift` and click the name of the file.
 
 |kitty| will ask you what you want to do with the remote file. You can choose
 to *Edit* it in which case kitty will download it and open it locally in your
-``EDITOR``. As you make changes to the file, they are automatically transferred
-to the remote computer. Note that this happens without needing to install *any*
-special software on the server, beyond ``ls`` that supports hyperlinks.
+:envvar:`EDITOR`. As you make changes to the file, they are automatically
+transferred to the remote computer. Note that this happens without needing
+to install *any* special software on the server, beyond ``ls`` that supports
+hyperlinks.
 
 .. versionadded:: 0.19.0
 
diff --git a/kitty/options/definition.py b/kitty/options/definition.py
index 953a0fb1c..facd72e63 100644
--- a/kitty/options/definition.py
+++ b/kitty/options/definition.py
@@ -2418,13 +2418,13 @@ starts in interactive mode and reads its startup rc files.
 opt('editor', '.',
     long_text='''
 The console editor to use when editing the kitty config file or similar tasks.
-The default value of ``.`` means to use the environment variables :envvar:`VISUAL`
-and :envvar:`EDITOR` in that order. Note that these environment variables have
-to be set when kitty starts, so if they're only set in shell startup scripts, but
-kitty is launched directly from your desktop, kitty will not see them. kitty does try
-to read the values from the shell as well, but this process is not entirely robust since
-there are a myriad different shells out there. In that case you're better off naming
-your favorite editor here.
+
+The default value of . means to use the environment variables :envvar:`VISUAL`
+and :envvar:`EDITOR` in that order. If these variables aren't set, kitty will
+run your shell (`$SHELL -l -c env`) to see if your shell config files set
+:envvar:`VISUAL` or :envvar:`EDITOR`. If that doesn't work, kitty will cycle
+through various known editors (`vim`, `emacs`, etc) and take the first one
+that exists on your system.
 '''
     )