# HG changeset patch
# User Rik <rik@octave.org>
# Date 1382131158 25200
# Node ID dd8db3f1c1dab6a5f2eceaf72a4a78a61253ef1e
# Parent  8031fc73f2915a9d9d0ec8d2f93329b6596a5be7
doc: Add information about High-Level/Low-Level calling forms for image, imagesc.

* scripts/image/image.m: Add info about High-Level/Low-Level calling forms to
docstring.

* scripts/image/imagesc.m: Add info about High-Level/Low-Level calling forms to
docstring.  Add @deftypefnx showing how to call function with prop/val pairs.

diff -r 8031fc73f291 -r dd8db3f1c1da scripts/image/image.m
--- a/scripts/image/image.m	Fri Oct 18 23:13:45 2013 +0200
+++ b/scripts/image/image.m	Fri Oct 18 14:19:18 2013 -0700
@@ -19,7 +19,8 @@
 ## -*- texinfo -*-
 ## @deftypefn  {Function File} {} image (@var{img})
 ## @deftypefnx {Function File} {} image (@var{x}, @var{y}, @var{img})
-## @deftypefnx {Function File} {} image (@dots{}, "@var{property}", @var{value}, @dots{})
+## @deftypefnx {Function File} {} image (@dots{}, "@var{prop}", @var{val}, @dots{})
+## @deftypefnx {Function File} {} image ("@var{prop1}", @var{val1}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} image (@dots{})
 ## Display a matrix as an indexed color image.
 ##
@@ -33,6 +34,9 @@
 ## @strong{Warning:} @var{x} and @var{y} are ignored when using gnuplot 4.0
 ## or earlier.
 ##
+## Multiple property/value pairs may be specified for the image object, but
+## they must appear in pairs.
+##
 ## The optional return value @var{h} is a graphics handle to the image.
 ##
 ## Implementation Note: The origin (0, 0) for images is located in the
@@ -44,6 +48,12 @@
 ## solution is to display the image and then plot the reversed ydata
 ## using, for example, @code{flipud (ydata)}.
 ##
+## Calling Forms: The @code{image} function can be called in two forms:
+## High-Level and Low-Level.  When invoked with normal options, the High-Level
+## form is used which first calls @code{newplot} to prepare the graphic figure
+## and axes.  When the only inputs to @code{image} are property/value pairs
+## the Low-Level form is used which creates a new instance of an image object
+## and inserts it in the current axes.
 ## @seealso{imshow, imagesc, colormap}
 ## @end deftypefn
 
diff -r 8031fc73f291 -r dd8db3f1c1da scripts/image/imagesc.m
--- a/scripts/image/imagesc.m	Fri Oct 18 23:13:45 2013 +0200
+++ b/scripts/image/imagesc.m	Fri Oct 18 14:19:18 2013 -0700
@@ -20,6 +20,8 @@
 ## @deftypefn  {Function File} {} imagesc (@var{img})
 ## @deftypefnx {Function File} {} imagesc (@var{x}, @var{y}, @var{img})
 ## @deftypefnx {Function File} {} imagesc (@dots{}, @var{climits})
+## @deftypefnx {Function File} {} imagesc (@dots{}, "@var{prop}", @var{val}, @dots{})
+## @deftypefnx {Function File} {} imagesc ("@var{prop1}", @var{val1}, @dots{})
 ## @deftypefnx {Function File} {} imagesc (@var{hax}, @dots{})
 ## @deftypefnx {Function File} {@var{h} =} imagesc (@dots{})
 ## Display a scaled version of the matrix @var{img} as a color image.  The
@@ -33,6 +35,14 @@
 ## of the matrix @var{img}.
 ##
 ## The optional return value @var{h} is a graphics handle to the image.
+##
+## Calling Forms: The @code{imagesc} function can be called in two forms:
+## High-Level and Low-Level.  When invoked with normal options, the High-Level
+## form is used which first calls @code{newplot} to prepare the graphic figure
+## and axes.  When the only inputs to @code{image} are property/value pairs
+## the Low-Level form is used which creates a new instance of an image object
+## and inserts it in the current axes.
+##
 ## @seealso{image, imshow, caxis}
 ## @end deftypefn