Expand docstring of vterm-prompt-detection-method

2 files changed, 18 insertions, 5 deletions

diff --git a/README.md b/README.md
index 0cacefa..cb181ce 100644
--- a/README.md
+++ b/README.md
@@ -38,15 +38,16 @@ For the long answer, let us discuss the differences between `eshell`, `shell`,
   directly manipulate the output using escape codes. Hence, many interactive
   applications (like the one aforementioned) work with `term`. However, `term`
   and `ansi-term` do not implement all the escapes codes needed, so some
-  programs do not work properly. Moreover, `term` has performance inferior
+  programs do not work properly. Moreover, `term` has inferior performance
   compared to standalone terminals, especially with large bursts of output.
 - `vterm`: like `term` it is a terminal emulator. Unlike `term`, the core of
   `vterm` is an external library written in C, `libvterm`. For this reason,
   `vterm` outperforms `term` and has a nearly universal compatibility with
   terminal applications.
 
-Therefore, vterm is not for you if you are using Windows, or if you cannot set
-up Emacs with support for modules.
+Vterm is not for you if you are using Windows, or if you cannot set up Emacs
+with support for modules. Otherwise, you should try vterm, as it provides a
+superior terminal experience in Emacs.
 
 Using `vterm` is like using Gnome Terminal inside Emacs: Vterm is fully-featured
 and fast, but is not as well integrated in Emacs as `eshell` (yet), so some of
diff --git a/vterm.el b/vterm.el
index 4650dda..b509fff 100644
--- a/vterm.el
+++ b/vterm.el
@@ -300,12 +300,24 @@ rendered as normal ones."
   :group 'vterm)
 
 (defcustom vterm-copy-exclude-prompt t
-  "When not nil the prompt is not included by `vterm-copy-mode-done'."
+  "When not-nil, the prompt is not included by `vterm-copy-mode-done'."
   :type 'boolean
   :group 'vterm)
 
 (defcustom vterm-use-vterm-prompt-detection-method t
-  "Should we use the vterm prompt tracker or the search from `term-prompt-regexp'?"
+  "When not-nil, the prompt is detected through the shell.
+
+Vterm needs to know where the shell prompt is to enable all the
+available features.  There are two supported ways to do this.
+First, the shell can inform vterm on the location of the prompt.
+This requires shell-side configuration: the escape code 51;A is
+used to set the current directory and prompt location.  This
+detection method is the most-reliable.  To use it, you have
+to change your shell prompt to print 51;A.
+
+The second method is using a regular expression. This method does
+not require any shell-side configuration. See
+`term-prompt-regexp', for more information."
   :type 'boolean
   :group 'vterm)