[Emacs-diffs] trunk r112905: Update Ehsell visual-commands documentation

[Aidan Gauland]

------------------------------------------------------------
revno: 112905
revision-id: address@hidden
parent: address@hidden
committer: Aidan Gauland <address@hidden>
branch nick: trunk
timestamp: Mon 2013-06-10 14:41:49 +1200
message:
  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.

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2013-06-10 00:32:49 +0000
+++ b/doc/misc/ChangeLog        2013-06-10 02:41:49 +0000
@@ -1,3 +1,9 @@
+2013-06-10  Aidan Gauland  <address@hidden>
+
+       * 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  <address@hidden>
 
        * epa.texi (Cryptographic operations on files): Update epa-decrypt-file.

=== modified file 'doc/misc/eshell.texi'
--- a/doc/misc/eshell.texi      2013-03-26 22:08:58 +0000
+++ b/doc/misc/eshell.texi      2013-06-10 02:41:49 +0000
@@ -701,14 +701,25 @@
 @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
address@hidden
-
+shells, IO is a little different.
+
address@hidden 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
address@hidden
+
address@hidden 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

=== modified file 'lisp/ChangeLog'
--- a/lisp/ChangeLog    2013-06-10 02:35:58 +0000
+++ b/lisp/ChangeLog    2013-06-10 02:41:49 +0000
@@ -1,3 +1,10 @@
+2013-06-10  Aidan Gauland  <address@hidden>
+
+       * 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  <address@hidden>
 
        * epa.el (epa-read-file-name): New function.  (Bug#14510)

=== modified file 'lisp/eshell/em-term.el'
--- a/lisp/eshell/em-term.el    2013-06-09 06:44:47 +0000
+++ b/lisp/eshell/em-term.el    2013-06-10 02:41:49 +0000
@@ -62,13 +62,19 @@
     "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 @@
 
   (\"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 @@
   (\"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"