From: Aidan Gauland <aidalgol@no8wireless.co.nz>
Date: Thu, 2 Jan 2014 09:27:46 +0000 (+1300)
Subject: * eshell.text (What is Eshell?): Add section about what not to use Eshell for.
X-Git-Tag: emacs-24.3.90~173^2^2~42^2~45^2~387^2~109
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=94ee87197f4fb33272972231f41d5db603d73afe;p=emacs.git

* eshell.text (What is Eshell?): Add section about what not to use Eshell for.
---

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index f64ed76341b..0612580dd62 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2014-01-02  Aidan Gauland  <aidalgol@amuri.net>
+
+	* eshell.text (What is Eshell?): Add section about what not to use
+	Eshell for.
+
 2013-12-23  Teodor Zlatanov  <tzz@lifelogs.com>
 
 	* emacs-gnutls.texi (Help For Users): Document `gnutls-verify-error'.
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 56983d9f97e..37ec9a54b6e 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -61,19 +61,19 @@ modify this GNU manual.''
 @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},
-@command{rc}, 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
+@command{bash}, @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 @@ handling the sort of tasks accomplished by those tools.
 * Key Index::
 @end menu
 
-@node What is Eshell?
-@chapter What is Eshell?
+@node Introduction
+@chapter Introduction
+@section What is Eshell?
 @cindex what is Eshell?
 @cindex Eshell, what it is
 
@@ -139,6 +140,24 @@ Any tool you use often deserves the time spent learning to master it.
 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)}.}
 
+@section What Eshell is not
+@cindex Eshell, what it is not
+@cindex what Eshell is not
+@cindex what isn't Eshell?
+
+Eshell is @emph{not} a replacement for system shells such as
+@command{bash} 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