--- a/doc/ChangeLog	Mon May 21 19:50:45 2007 +0000
+++ b/doc/ChangeLog	Mon May 21 19:53:58 2007 +0000
@@ -1,5 +1,9 @@
 2007-05-21  Søren Hauberg  <hauberg@gmail.com>
 
+        * interpreter/eval.txi: Partition the chapter into sections.
+        Describe evalin and assignin functions using text from Paul
+	Kienzle.
+
         * interpreter/func.txi: New section describing load path.
         Improve 'inline' and 'command' sections.
 

--- a/doc/interpreter/eval.txi	Mon May 21 19:50:45 2007 +0000
+++ b/doc/interpreter/eval.txi	Mon May 21 19:53:58 2007 +0000
@@ -10,18 +10,28 @@
 a file.
 
 Sometimes, you may find it necessary to evaluate an expression that has
-been computed and stored in a string, or use a string as the name of a
-function to call.  The @code{eval} and @code{feval} functions allow you
-to do just that, and are necessary in order to evaluate commands that
-are not known until run time, or to write functions that will need to
-call user-supplied functions.
+been computed and stored in a string, which is exactly what the
+@code{eval} lets you do.
 
 @DOCSTRING(eval)
 
-@DOCSTRING(feval)
+@menu
+* Calling a Function by its Name::
+* Evaluation in a Different Context::
+@end menu
+
+@node Calling a Function by its Name
+@section Calling a Function by its Name
 
-Here is a simple-minded function using @code{feval} that finds the root
-of a user-supplied function of one variable using Newton's method.
+The @code{feval} function allow you to call a function from a string
+containing its name. This is useful when writing a function that need to
+call user-supplied functions. The @code{feval} function takes the name
+of the function to call as its first argument, and the remaining 
+arguments are given to the function.
+
+The following example is a simple-minded function using @code{feval}
+that finds the root of a user-supplied function of one variable using
+Newton's method.
 
 @example
 @group
@@ -59,10 +69,92 @@
 functions and should not be taken too seriously.  In addition to using a
 more robust algorithm, any serious code would check the number and type
 of all the arguments, ensure that the supplied function really was a
-function, etc.  See @xref{Predicates for Numeric Objects}, for example,
-for a list of predicates for numeric objects, and @xref{Status of
+function, etc.  @xref{Predicates for Numeric Objects}, for example,
+for a list of predicates for numeric objects, and see @ref{Status of
 Variables}, for a description of the @code{exist} function.
 
+@DOCSTRING(feval)
+
+@node Evaluation in a Different Context
+@section Evaluation in a Different Context
+
+Before you evaluate an expression you need to substitute
+the values of the variables used in the expression.  These
+are stored in the symbol table.  Whenever the interpreter
+starts a new function it saves the current symbol table
+and creates a new one, initializing it with the list of
+function parameters and a couple of predefined variables
+such as @code{nargin}.  Expressions inside the function use the
+new symbol table.
+
+Sometimes you want to write a function so that when you
+call it, it modifies variables in your own context.  This
+allows you to use a pass-by-name style of function,
+which is similar to using a pointer in programming languages such
+as C.
+
+Consider how you might write @code{save} and @code{load} as
+m-files.  For example,
+
+@example
+function create_data
+  x = linspace (0, 10, 10);
+  y = sin (x);
+  save mydata x y
+endfunction
+@end example
+
+With @code{evalin}, you could write save as follows:
+
+@example
+function save (file, name1, name2)
+  f = open_save_file (file);
+  save_var(f, name1, evalin ("caller", name1));
+  save_var(f, name2, evalin ("caller", name2));
+endfunction
+@end example
+
+@noindent
+Here, @samp{caller} is the @code{create_data} function and @code{name1}
+is the string @code{"x"}, which evaluates simply as the value of @code{x}.
+
+You later want to load the values back from @code{mydata}
+in a different context:
+
+@example
+function process_data
+  load mydata
+  @dots{} do work @dots{}
+endfunction
+@end example
+
+@noindent
+With @code{assignin}, you could write @code{load} as follows:
+
+@example
+function load (file)
+  f = open_load_file (file);
+  [name, val] = load_var (f);
+  assignin ("caller", name, val);
+  [name, val] = load_var (f);
+  assignin ("caller", name, val);
+endfunction
+@end example
+
+@noindent
+Here, @samp{caller} is the @code{process_data} function.
+
+You can set and use variables at the command prompt
+using the context @samp{base} rather than @samp{caller}.
+
+These functions are rarely used in practice.  One
+example is the @code{fail (@samp{code}, @samp{pattern})} function
+which evaluates @samp{code} in the caller's context and
+checks that the error message it produces matches
+the given pattern.  Other examples such as @code{save} and @code{load}
+are written in C++ where all octave variables
+are in the @samp{caller} context and @code{evalin} is not needed.
+
 @DOCSTRING(evalin)
 
 @DOCSTRING(assignin)