From: Aidan Gauland Date: Mon, 10 Jun 2013 02:41:49 +0000 (+1200) Subject: Update Ehsell visual-commands documentation X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~2026^2~23 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=fa4729064fd0569682924dfa4d0621b72426066b;p=emacs.git 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 ce2852e90f8..4cae3d0a478 100644 --- a/doc/misc/ChangeLog +++ b/doc/misc/ChangeLog @@ -1,3 +1,9 @@ +2013-06-10 Aidan Gauland + + * 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 * epa.texi (Cryptographic operations on files): Update epa-decrypt-file. diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi index dca95da2d10..0da422fe14f 100644 --- 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 2e95113fbb6..0749b6aa9bd 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,10 @@ +2013-06-10 Aidan Gauland + + * 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 * 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 1d4b2a59d4b..2932f443e4f 100644 --- 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 --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"