--- a/scripts/plot/appearance/text.m	Mon Jul 22 23:51:01 2019 -0400
+++ b/scripts/plot/appearance/text.m	Mon Jul 29 09:11:03 2019 -0700
@@ -38,8 +38,43 @@
 ## The optional return value @var{h} is a vector of graphics handles to the
 ## created text objects.
 ##
-## Programming Note: The full list of properties is documented at
+## Example 1 : multi-line text via 3 different methods
+##
+## @example
+## @group
+## text (0.5, 0.8, @{"Line 1", "Line 2"@})
+## text (0.5, 0.6, ["Line 1"; "Line 2"])
+## text (0.5, 0.4, "Line 1\nLine 2")
+## @end group
+## @end example
+##
+## Example 2 : text at multiple locations
+##
+## @example
+## @group
+## text ([0.2, 0.2], [0.8, 0.6], "Same text at two locations")
+## text ([0.4, 0.4], [0.8, 0.6], @{"Point 1 Text", "Point 2 text"@})
+## text ([0.6, 0.6], [0.8, 0.6], @{@{"Point 1 Line 1", "Point 1 Line 2@},
+##                                "Point 2 text"@})
+## @end group
+## @end example
+##
+## Example 2 : adjust appearance using text properties
+##
+## @example
+## @group
+## ht = text (0.5, 0.5, "Hello World", "fontsize", 20);
+## set (ht, "color", "red");
+## @end group
+## @end example
+##
+## Programming Notes: The full list of properties is documented at
 ## @ref{Text Properties,,Text Properties}.
+##
+## Any numeric entries in a cell array will be converted to text using
+## @code{sprintf ("%g")}.  For more precise control of the appearance convert
+## any numeric entries to strings using @code{num2str}, @code{sprintf}, etc.,
+## before calling @code{text}.
 ## @seealso{gtext, title, xlabel, ylabel, zlabel}
 ## @end deftypefn
 
@@ -128,7 +163,7 @@
       string = repmat ({string}, [nx, 1]);
       nt = nx;
     else
-      error ("text: Invalid combination of points and text strings");
+      error ("text: invalid combination of points and text strings");
     endif
 
     ## Escape special keywords
@@ -138,10 +173,15 @@
 
   elseif (iscell (string))
 
+    if (! iscellstr (string))
+      ## Matlab compatibility: convert any numeric cells to strings
+      string = cell2cellstr (string);
+    endif
+
     nt = numel (string);
     if (nx == 1)
       ## Single text object with one or more lines
-      string = {cellstr(string)};
+      string = {string};
       nt = 1;
     elseif (nx > 1 && nt == nx)
       ## Multiple text objects with different strings
@@ -150,7 +190,7 @@
       string = repmat ({cellstr(string)}, [nx, 1]);
       nt = nx;
     else
-      error ("text: Invalid combination of points and text strings");
+      error ("text: invalid combination of points and text strings");
     endif
 
   else
@@ -186,6 +226,13 @@
 
 endfunction
 
+## Helper function converts any numeric entries to strings
+function cstr = cell2cellstr (c)
+  cstr = c;
+  idx = cellfun (@isnumeric, c);
+  cstr(idx) = cellfun (@(x) sprintf ("%g", x), c(idx), "uniformoutput", false);
+endfunction
+
 
 %!demo
 %! clf;
@@ -378,10 +425,19 @@
 %!   close (hf);
 %! end_unwind_protect
 
+%!test <*56395>
+%! hf = figure ("visible", "off");
+%! unwind_protect
+%!   ht = text (.3, .8, {"Hello", 'world', [], 1e7});
+%!   assert (get (ht, "string"), {"Hello"; "world"; ""; "1e+07"});
+%! unwind_protect_cleanup
+%!   close (hf);
+%! end_unwind_protect
+
 ## Test input validation
 %!error <X, Y, and Z coordinates must match> text (1, [2 3], "foobar")
 %!error <X, Y, and Z coordinates must match> text (1, 2, [3 4], "foobar")
-%!error <Invalid combination> text ([1 2], [3, 4], ['a'; 'b'; 'c'])
-%!error <Invalid combination> text ([1 2], [3, 4], {'a', 'b', 'c'})
+%!error <Invalid call to text> text (1,2, "text", "opt1")
+%!error <invalid combination> text ([1 2], [3, 4], ['a'; 'b'; 'c'])
+%!error <invalid combination> text ([1 2], [3, 4], {'a', 'b', 'c'})
 %!error <STRING must be a character string> text (1, 2, 3)
-%!error text ("abc")