2 files changed, 16 insertions, 1 deletions

diff --git a/doc/emacs/misc.texi b/doc/emacs/misc.texi
index a0d79711f10..63eb00b2357 100644
--- a/doc/emacs/misc.texi
+++ b/doc/emacs/misc.texi
@@ -896,6 +896,19 @@ also rename the @file{*shell*} buffer using @kbd{M-x rename-uniquely},
 then create a new @file{*shell*} buffer using plain @kbd{M-x shell}.
 Subshells in different buffers run independently and in parallel.
 
+  Emacs attempts to keep track of what the current directory is by
+looking at the commands you enter, looking for @samp{cd} commands and
+the like.  This is an error-prone solution, since there are many ways
+to change the current directory, so Emacs also looks for special
+@acronym{OSC} (Operating System Commands} escape codes that are
+designed to convey this information in a more reliable fashion.  You
+should arrange for your shell to print the appropriate escape sequence
+at each prompt, for instance with the following command:
+
+@example
+printf "\e]7;file://%s%s\e\\" "$HOSTNAME" "$PWD"
+@end example
+
 @vindex explicit-shell-file-name
 @cindex environment variables for subshells
 @cindex @env{ESHELL} environment variable
diff --git a/lisp/shell.el b/lisp/shell.el
index 627c48e35fb..47887433d9f 100644
--- a/lisp/shell.el
+++ b/lisp/shell.el
@@ -1033,7 +1033,9 @@ Environment variables are expanded, see function `substitute-in-file-name'."
   "Toggle directory tracking in this shell buffer (Shell Dirtrack mode).
 
 The `dirtrack' package provides an alternative implementation of
-this feature; see the function `dirtrack-mode'."
+this feature; see the function `dirtrack-mode'.  Also see
+`comint-osc-directory-tracker' for an escape-sequence based
+solution."
   :lighter nil
   (setq list-buffers-directory (if shell-dirtrack-mode default-directory))
   (if shell-dirtrack-mode