Mention term.el's \032 dir tracking in commentary (Bug#19524)

* lisp/term.el: Mention both forms of directory tracking in
commentary.  Remove obsolete ChangeLog comments.  Move more relevant
summary comments to the top.

1 files changed, 52 insertions, 91 deletions

diff --git a/lisp/term.el b/lisp/term.el
index 9785ce30249..fb624e4b7a8 100644
--- a/lisp/term.el
+++ b/lisp/term.el
@@ -33,6 +33,21 @@
 
 ;;; Commentary:
 
+;; This file defines a general command-interpreter-in-a-buffer package
+;; (term mode).  The idea is that you can build specific process-in-a-buffer
+;; modes on top of term mode -- e.g., lisp, shell, scheme, T, soar, ....
+;; This way, all these specific packages share a common base functionality,
+;; and a common set of bindings, which makes them easier to use (and
+;; saves code, implementation time, etc., etc.).
+
+;; If, instead of `term', you call `ansi-term', you get multiple term
+;; buffers, after every new call ansi-term opens a new
+;; "*ansi-term*<xx>" window, where <xx> is, as usual, a number...
+
+;; For hints on converting existing process modes (e.g., tex-mode,
+;; background, dbx, gdb, kermit, prolog, telnet) to use term-mode
+;; instead of shell-mode, see the notes at the end of this file.
+
 ;; Speed considerations and a few caveats
 ;; --------------------------------------
 ;;
@@ -85,13 +100,6 @@
 ;; # By default nobody can't do anything
 ;; deny root            *
 ;;
-;;
-;;             ----------------------------------------
-;;
-;;  If, instead of 'term', you call 'ansi-term', you get multiple term
-;; buffers, after every new call ansi-term opens a new *ansi-term*<xx> window,
-;; where <xx> is, as usual, a number...
-;;
 ;;             ----------------------------------------
 ;;
 ;;  With the term-buffer-maximum-size you can finally decide how many
@@ -100,7 +108,6 @@
 ;;
 ;;             ----------------------------------------
 ;;
-;;
 ;;  ANSI colorization should work well, I've decided to limit the interpreter
 ;; to five outstanding commands (like ESC [ 01;04;32;41;07m.
 ;;  You shouldn't need more, if you do, tell me and I'll increase it.  It's
@@ -115,38 +122,6 @@
 ;;  - Add hooks to allow raw-mode keys to be configurable
 ;;  - Which keys are better ? \eOA or \e[A ?
 ;;
-;;
-;;  Changes:
-;;
-;; V4.0 January 1997
-;;
-;;   - Huge reworking of the faces code: now we only have roughly 20-30
-;;     faces for everything so we're even faster than the old md-term.el !
-;;   - Finished removing all the J-Shell code.
-;;
-;;  V3.0 January 1997
-;;
-;;  - Now all the supportable ANSI commands work well.
-;;  - Reworked a little the code: much less jsh-inspired stuff
-;;
-;;  V2.3 November
-;;
-;;  - Now all the faces are accessed through an array: much cleaner code.
-;;
-;;  V2.2 November 4 1996
-;;
-;;  - Implemented ANSI output colorization ( a bit rough but enough for
-;;    color_ls )
-;;
-;;  - Implemented a maximum limit for the scroll buffer (stolen from
-;;    comint.el)
-;;
-;;  v2.1 October 28 1996, first public release
-;;
-;;  - Some new keybindings for term-char mode ( notably home/end/...)
-;;  - Directory, hostname and username tracking via ange-ftp
-;;  - Multi-term capability via the ansi-term call
-;;
 ;;  ----------------------------------------------------------------
 ;;  You should/could have something like this in your .emacs to take
 ;;  full advantage of this package
@@ -160,7 +135,6 @@
 ;;                   (auto-fill-mode -1)
 ;;                   (setq tab-width 8 ))))
 ;;
-;;
 ;;             ----------------------------------------
 ;;
 ;;  If you want to use color ls the best setup is to have a different file
@@ -171,7 +145,6 @@
 ;;
 ;;             ----------------------------------------
 ;;
-;;
 ;;  # Configuration file for the color ls utility
 ;;  # This file goes in the /etc directory, and must be world readable.
 ;;  # You can copy this file to .dir_colors in your $HOME directory to
@@ -228,17 +201,23 @@
 ;;  .xbm 01;35
 ;;  .xpm 01;35
 ;;
-;;
 ;;             ----------------------------------------
 ;;
-;;  Notice: for directory/host/user tracking you need to have something
-;; like this in your shell startup script (this is for a POSIXish shell
-;; like Bash but should be quite easy to port to other shells).
+;; There are actually two methods for directory tracking, one
+;; implemented in `term-command-hook' which sets the directory
+;; according to an escape sequence of the form "\032<directory>\n".
+;; Some shells like bash will already send this escape sequence when
+;; they detect they are running in Emacs.  This can be configured or
+;; disabled on the Emacs side by setting `term-command-hook' to
+;; a different function.
 ;;
-;; For troubleshooting in Bash, you can check the definition of the
-;; custom functions with the "type" command.  e.g. "type cd".  If you
-;; do not see the expected definition from the config below, then the
-;; directory tracking will not work.
+;; The second method is in `term-handle-ansi-terminal-messages' which
+;; sets user, host, and directory according to escape sequences of the
+;; form "\033AnSiTc <directory>\n" (replace the "c" with "u" and "h"
+;; for user and host, respectively).  If the user and host don't
+;; match, it will set directory to a remote one, so it is important to
+;; set user and host correctly first.  See the example bash
+;; configuration below.
 ;;
 ;;             ----------------------------------------
 ;;
@@ -262,42 +241,24 @@
 ;;
 ;;              # The \033 stands for ESC.
 ;;              # There is a space between "AnSiT?" and $whatever.
+;;              printf '\033AnSiTh %s\n' "$HOSTNAME"
+;;              printf '\033AnSiTu %s\n' "$USER"
+;;              printf '\033AnSiTc %s\n' "$PWD"
 ;;
 ;;              cd()    { command cd    "$@"; printf '\033AnSiTc %s\n' "$PWD"; }
 ;;              pushd() { command pushd "$@"; printf '\033AnSiTc %s\n' "$PWD"; }
 ;;              popd()  { command popd  "$@"; printf '\033AnSiTc %s\n' "$PWD"; }
 ;;
-;;              printf '\033AnSiTc %s\n' "$PWD"
-;;              printf '\033AnSiTh %s\n' "$HOSTNAME"
-;;              printf '\033AnSiTu %s\n' "$USER"
-;;
 ;;              # Use custom dircolors in term buffers.
 ;;              # eval $(dircolors $HOME/.emacs_dircolors)
 ;;      esac
 ;;
 ;;      # ...
 ;;
-;;
-
-;;; Original Commentary:
-;; ---------------------
-
-;; The changelog is at the end of this file.
-
-;; Please send me bug reports, bug fixes, and extensions, so that I can
-;; merge them into the master source.
-;;     - Per Bothner (bothner@cygnus.com)
-
-;; This file defines a general command-interpreter-in-a-buffer package
-;; (term mode).  The idea is that you can build specific process-in-a-buffer
-;; modes on top of term mode -- e.g., lisp, shell, scheme, T, soar, ....
-;; This way, all these specific packages share a common base functionality,
-;; and a common set of bindings, which makes them easier to use (and
-;; saves code, implementation time, etc., etc.).
-
-;; For hints on converting existing process modes (e.g., tex-mode,
-;; background, dbx, gdb, kermit, prolog, telnet) to use term-mode
-;; instead of shell-mode, see the notes at the end of this file.
+;; For troubleshooting in Bash, you can check the definition of the
+;; custom functions with the "type" command.  e.g. "type cd".  If you
+;; do not see the expected definition from the config below, then the
+;; directory tracking will not work.
 
 
 ;; Brief Command Documentation:
@@ -305,21 +266,21 @@
 ;; Term Mode Commands: (common to all derived modes, like cmushell & cmulisp
 ;; mode)
 ;;
-;; m-p      term-previous-input           Cycle backwards in input history
-;; m-n      term-next-input               Cycle forwards
-;; m-r     term-previous-matching-input  Previous input matching a regexp
-;; m-s     comint-next-matching-input      Next input that matches
+;; M-p     term-previous-input           Cycle backwards in input history
+;; M-n     term-next-input               Cycle forwards
+;; M-r     term-previous-matching-input  Previous input matching a regexp
+;; M-s     comint-next-matching-input    Next input that matches
 ;; return  term-send-input
-;; c-c c-a term-bol                      Beginning of line; skip prompt.
-;; c-d      term-delchar-or-maybe-eof     Delete char unless at end of buff.
-;; c-c c-u term-kill-input                  ^u
-;; c-c c-w backward-kill-word               ^w
-;; c-c c-c term-interrupt-subjob            ^c
-;; c-c c-z term-stop-subjob                 ^z
-;; c-c c-\ term-quit-subjob                 ^\
-;; c-c c-o term-kill-output                 Delete last batch of process output
-;; c-c c-r term-show-output                 Show last batch of process output
-;; c-c c-h term-dynamic-list-input-ring  List input history
+;; C-c C-a term-bol                      Beginning of line; skip prompt.
+;; C-d     term-delchar-or-maybe-eof     Delete char unless at end of buff.
+;; C-c C-u term-kill-input               ^u
+;; C-c C-w backward-kill-word            ^w
+;; C-c C-c term-interrupt-subjob         ^c
+;; C-c C-z term-stop-subjob              ^z
+;; C-c C-\ term-quit-subjob              ^\
+;; C-c C-o term-kill-output              Delete last batch of process output
+;; C-c C-r term-show-output              Show last batch of process output
+;; C-c C-h term-dynamic-list-input-ring  List input history
 ;;
 ;; Not bound by default in term-mode
 ;; term-send-invisible                  Read a line w/o echo, and send to proc
@@ -329,8 +290,8 @@
 ;; term-replace-by-expanded-filename    Expand and complete filename at point;
 ;;                                      replace with expanded/completed name.
 ;; term-kill-subjob                     No mercy.
-;; term-show-maximum-output            Show as much output as possible.
-;; term-continue-subjob         Send CONT signal to buffer's process
+;; term-show-maximum-output             Show as much output as possible.
+;; term-continue-subjob                 Send CONT signal to buffer's process
 ;;                                      group.  Useful if you accidentally
 ;;                                      suspend your process (with C-c C-z).