Update Ehsell visual-commands documentation

* eshell.texi (Input/Output): Expand to cover new visual-command
options, eshell-visual-subcommands and eshell-visual-options.
Divide into separate Visual Commands and Redirection sections.
* eshell/em-term.el (eshell-visual-commands)
(eshell-visual-subcommands)
(eshell-visual-options): Add summary line to docstrings.  Add
cross-references.

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index ce2852e90f8e290193706b53667b845ad5d7b6ba..4cae3d0a478f84094a05fc3c902c4b27a2b6a65b 100644 (file)
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,9 @@
+2013-06-10  Aidan Gauland  <aidalgol@amuri.net>
+
+       * eshell.texi (Input/Output): Expand to cover new visual-command
+       options, eshell-visual-subcommands and eshell-visual-options.
+       Divide into separate Visual Commands and Redirection sections.
+
 2013-06-10  Glenn Morris  <rgm@gnu.org>
 
        * epa.texi (Cryptographic operations on files): Update epa-decrypt-file.

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index dca95da2d10a9a41c63b64e58eba0519389d3452..0da422fe14fe416ae241608d6aee005337ee88f7 100644 (file)
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -701,14 +701,25 @@ groups ``eshell-glob'' and ``eshell-pred''.
 @node Input/Output
 @chapter Input/Output
 Since Eshell does not communicate with a terminal like most command
-shells, IO is a little different.  If you try to run programs from
-within Eshell that are not line-oriented, such as programs that use
-ncurses, you will just get garbage output, since the Eshell buffer is
-not a terminal emulator.  Eshell solves this problem by running
-specified commands in Emacs's terminal emulator; to let Eshell know
-which commands need to be run in a terminal, add them to the list
-@var{eshell-visual-commands}.
-
+shells, IO is a little different.
+
+@section Visual Commands
+If you try to run programs from within Eshell that are not
+line-oriented, such as programs that use ncurses, you will just get
+garbage output, since the Eshell buffer is not a terminal emulator.
+Eshell solves this problem by running such programs in Emacs's
+terminal emulator.
+
+Programs that need a terminal to display output properly are referred
+to in this manual as ``visual commands,'' because they are not simply
+line-oriented.  You must tell Eshell which commands are visual, by
+adding them to @var{eshell-visual-commands}; for commands that are
+visual for only certain @emph{sub}-commands -- e.g. @samp{git log} but
+not @samp{git status} -- use @var{eshell-visual-subcommands}; and for
+commands that are visual only when passed certain options, use
+@var{eshell-visual-options}.
+
+@section Redirection
 Redirection is mostly the same in Eshell as it is in other command
 shells.  The output redirection operators @code{>} and @code{>>} as
 well as pipes are supported, but there is not yet any support for

diff --git a/lisp/ChangeLog b/lisp/ChangeLog
index 2e95113fbb626b7a650cfd5d214a596e708e4371..0749b6aa9bd3250b2d1459b95b0158f07afdc3b1 100644 (file)
--- a/lisp/ChangeLog
+++ b/lisp/ChangeLog
@@ -1,3 +1,10 @@
+2013-06-10  Aidan Gauland  <aidalgol@amuri.net>
+
+       * eshell/em-term.el (eshell-visual-commands)
+       (eshell-visual-subcommands)
+       (eshell-visual-options): Add summary line to docstrings.  Add
+       cross-references.
+
 2013-06-10  Glenn Morris  <rgm@gnu.org>
 
        * epa.el (epa-read-file-name): New function.  (Bug#14510)

diff --git a/lisp/eshell/em-term.el b/lisp/eshell/em-term.el
index 1d4b2a59d4b64e2444b4f07532424f9d4284f101..2932f443e4fcac577dc0fb9c370d832bd7a85159 100644 (file)
--- a/lisp/eshell/em-term.el
+++ b/lisp/eshell/em-term.el
@@ -62,13 +62,19 @@ which commands are considered visual in nature."
     "less" "more"                       ; M-x view-file
     "lynx" "ncftp"                      ; w3.el, ange-ftp
     "pine" "tin" "trn" "elm")           ; GNUS!!
-  "A list of commands that present their output in a visual fashion."
+  "A list of commands that present their output in a visual fashion.
+
+Commands listed here are run in a term buffer.
+
+See also `eshell-visual-subcommands' and `eshell-visual-options'."
   :type '(repeat string)
   :group 'eshell-term)
 
 (defcustom eshell-visual-subcommands
   nil
-  "An alist of the form
+  "An alist of subcommands that present their output in a visual fashion.
+
+An alist of the form
 
   ((COMMAND1 SUBCOMMAND1 SUBCOMMAND2...)
    (COMMAND2 SUBCOMMAND1 ...))
@@ -78,7 +84,9 @@ visual fashion.  A likely entry is
 
   (\"git\" \"log\" \"diff\" \"show\")
 
-because git shows logs and diffs using a pager by default."
+because git shows logs and diffs using a pager by default.
+
+See also `eshell-visual-commands' and `eshell-visual-options'."
   :type '(repeat (cons (string :tag "Command")
                       (repeat (string :tag "Subcommand"))))
   :version "24.4"
@@ -97,7 +105,9 @@ fashion.  For example, a sensible entry would be
   (\"git\" \"--help\")
 
 because \"git <command> --help\" shows the command's
-documentation with a pager."
+documentation with a pager.
+
+See also `eshell-visual-commands' and `eshell-visual-subcommands'."
   :type '(repeat (cons (string :tag "Command")
                       (repeat (string :tag "Option"))))
   :version "24.4"