--- a/libinterp/corefcn/lookup.cc	Sat Sep 02 21:58:35 2017 +0200
+++ b/libinterp/corefcn/lookup.cc	Sat Sep 02 17:54:22 2017 -0700
@@ -191,51 +191,51 @@
        doc: /* -*- texinfo -*-
 @deftypefn  {} {@var{idx} =} lookup (@var{table}, @var{y})
 @deftypefnx {} {@var{idx} =} lookup (@var{table}, @var{y}, @var{opt})
-Lookup values in a sorted table.
+Lookup values in a @strong{sorted} table.
 
 This function is usually used as a prelude to interpolation.
 
 If table is increasing and @code{idx = lookup (table, y)}, then
-@code{table(idx(i)) <= y(i) < table(idx(i+1))} for all @code{y(i)} within
-the table.  If @code{y(i) < table(1)} then @code{idx(i)} is 0.  If
+@code{table(idx(i)) <= y(i) < table(idx(i+1))} for all @code{y(i)} within the
+table.  If @code{y(i) < table(1)} then @code{idx(i)} is 0.  If
 @code{y(i) >= table(end)} or @code{isnan (y(i))} then @code{idx(i)} is
 @code{n}.
 
-If the table is decreasing, then the tests are reversed.
-For non-strictly monotonic tables, empty intervals are always skipped.
-The result is undefined if @var{table} is not monotonic, or if
-@var{table} contains a NaN.
+If the table is decreasing, then the tests are reversed.  For non-strictly
+monotonic tables, empty intervals are always skipped.  The result is undefined
+if @var{table} is not monotonic, or if @var{table} contains a NaN.
 
-The complexity of the lookup is O(M*log(N)) where N is the size of
-@var{table} and M is the size of @var{y}.  In the special case when @var{y}
-is also sorted, the complexity is O(min(M*log(N),M+N)).
+The complexity of the lookup is O(M*log(N)) where N is the size of @var{table}
+and M is the size of @var{y}.  In the special case when @var{y} is also sorted,
+the complexity is O(min (M*log(N), M+N)).
 
-@var{table} and @var{y} can also be cell arrays of strings
-(or @var{y} can be a single string).  In this case, string lookup
-is performed using lexicographical comparison.
+@var{table} and @var{y} can also be cell arrays of strings (or @var{y} can be a
+single string).  In this case, string lookup is performed using lexicographical
+comparison.
 
 If @var{opts} is specified, it must be a string with letters indicating
 additional options.
 
 @table @code
 @item m
-@code{table(idx(i)) == val(i)} if @code{val(i)}
-occurs in table; otherwise, @code{idx(i)} is zero.
+Match.  @code{table(idx(i)) == val(i)} if @code{val(i)} occurs in table;
+otherwise, @code{idx(i)} is zero.
 
 @item b
-@code{idx(i)} is a logical 1 or 0, indicating whether
-@code{val(i)} is contained in table or not.
+Boolean.  @code{idx(i)} is a logical 1 or 0, indicating whether @code{val(i)}
+is contained in table or not.
 
 @item l
-For numeric lookups
-the leftmost subinterval shall be extended to infinity (i.e., all indices
-at least 1)
+Left.  For numeric lookups the leftmost subinterval shall be extended to
+infinity (i.e., all indices at least 1).
 
 @item r
-For numeric lookups
-the rightmost subinterval shall be extended to infinity (i.e., all indices
-at most n-1).
+Right.  For numeric lookups the rightmost subinterval shall be extended to
+infinity (i.e., all indices at most n-1).
 @end table
+
+@strong{Note}: If @var{table} is not sorted the results from @code{lookup}
+will be unpredictable.
 @end deftypefn */)
 {
   int nargin = args.length ();