[Emacs-diffs] trunk r115830: * eshell.text (What is Eshell?): Add section about what not to use Eshell for.

[Aidan Gauland]

------------------------------------------------------------
revno: 115830
revision-id: address@hidden
parent: address@hidden
committer: Aidan Gauland <address@hidden>
branch nick: trunk
timestamp: Thu 2014-01-02 22:27:46 +1300
message:
  * eshell.text (What is Eshell?): Add section about what not to use Eshell for.
modified:
  doc/misc/ChangeLog             changelog-20091113204419-o5vbwnq5f7feedwu-6331
  doc/misc/eshell.texi           
eshell.texi-20091113204419-o5vbwnq5f7feedwu-6299

=== modified file 'doc/misc/ChangeLog'
--- a/doc/misc/ChangeLog        2014-01-01 07:43:34 +0000
+++ b/doc/misc/ChangeLog        2014-01-02 09:27:46 +0000
@@ -1,3 +1,8 @@
+2014-01-02  Aidan Gauland  <address@hidden>
+
+       * eshell.text (What is Eshell?): Add section about what not to use
+       Eshell for.
+
 2013-12-23  Teodor Zlatanov  <address@hidden>
 
        * emacs-gnutls.texi (Help For Users): Document `gnutls-verify-error'.

=== modified file 'doc/misc/eshell.texi'
--- a/doc/misc/eshell.texi      2014-01-01 08:31:29 +0000
+++ b/doc/misc/eshell.texi      2014-01-02 09:27:46 +0000
@@ -61,19 +61,19 @@
 @node Top
 @top Eshell
 
-Eshell is a shell-like command interpreter
-implemented in Emacs Lisp.  It invokes no external processes except for
-those requested by the user.  It is intended to be a functional
-replacement for command shells such as @command{bash}, @command{zsh},
address@hidden, or @command{4dos}; since Emacs itself is capable of
-handling the sort of tasks accomplished by those tools.
+Eshell is a shell-like command interpreter implemented in Emacs Lisp.
+It invokes no external processes except for those requested by the
+user.  It is intended to be an alternative to the @xref{Lisp
+Interaction, IELM, , elisp, The Emacs Lisp Reference Manual} REPL for
+Emacs @emph{and} with an interface similar to command shells such as
address@hidden, @command{zsh}, @command{rc}, or @command{4dos}.
 @c This manual is updated to release 2.4 of Eshell.
 
 @insertcopying
 @end ifnottex
 
 @menu
-* What is Eshell?::             A brief introduction to the Emacs Shell.
+* Introduction::             A brief introduction to the Emacs Shell.
 * Command basics::              The basics of command usage.
 * Commands::
 * Expansion::
@@ -87,8 +87,9 @@
 * Key Index::
 @end menu
 
address@hidden What is Eshell?
address@hidden What is Eshell?
address@hidden Introduction
address@hidden Introduction
address@hidden What is Eshell?
 @cindex what is Eshell?
 @cindex Eshell, what it is
 
@@ -139,6 +140,24 @@
 looks like: But don't let it fool you; once you know what's going on,
 it's easier than it looks: @code{ls -lt **/*.doc(Lk+50aM+5)}.}
 
address@hidden What Eshell is not
address@hidden Eshell, what it is not
address@hidden what Eshell is not
address@hidden what isn't Eshell?
+
+Eshell is @emph{not} a replacement for system shells such as
address@hidden or @command{zsh}.  Use Eshell when you want to move
+text between Emacs and external processes; if you only want to pipe
+output from one external process to another, to another, use a system
+shell, because Emacs's IO system is buffer oriented, not stream
+oriented, and is very inefficient at such tasks.  If you want to write
+shell scripts in Eshell, don't; either write an elisp library or use a
+system shell.
+
+Some things Eshell just doesn't do well.  It fills the niche between
+IELM and your system shell, where the peculiar use-cases lie, and it
+is less than ideal outside that niche.
+
 @menu
 * Contributors to Eshell::      People who have helped out!
 @end menu