# HG changeset patch
# User Kai T. Ohlhus <k.ohlhus@gmail.com>
# Date 1571372782 -32400
# Node ID 37f9eb2c05e04ecf9634f94f61a557565a3cc602
# Parent  7a871724d4b0ccd0a32e8085196f60d9ea9de713
doc: improve format() docstring and NEWS announcement.

* NEWS: Mention multiple arguments can be used, the rules, and give an example.

* libinterp/corefcn/pr-output.cc: Document rules for multiple options.

diff -r 7a871724d4b0 -r 37f9eb2c05e0 NEWS
--- a/NEWS	Thu Oct 17 11:59:26 2019 -0400
+++ b/NEWS	Fri Oct 18 13:26:22 2019 +0900
@@ -24,12 +24,22 @@
   'A-F' instead.  The previous uppercase formats, `E` and `G`, no longer
   control the case of the output.
 
+  Additionally, the `format` command can be called with multiple options
+  for controlling the format, spacing, and case in arbitrary order.
+  For example:
+
+     format long e uppercase loose
+
+  Note, that in case of multiple competing format options the most right
+  one is used and in case of an error the previous format remains
+  unchanged.
+
 - New warnings have been added about questionable uses of the colon ':'
   range operator.  Each has a new warning ID so that it can be disabled
   if desired.
     Octave:colon-complex-argument   : when any arg is complex
     Octave:colon-nonscalar-argument : when any arg is non-scalar
-  
+
 #### Graphics backend
 
 - Graphic primitives now accept a color property value of `"none"`
diff -r 7a871724d4b0 -r 37f9eb2c05e0 libinterp/corefcn/pr-output.cc
--- a/libinterp/corefcn/pr-output.cc	Thu Oct 17 11:59:26 2019 -0400
+++ b/libinterp/corefcn/pr-output.cc	Fri Oct 18 13:26:22 2019 +0900
@@ -3813,7 +3813,8 @@
 for matrices).  If @code{format} is invoked without any options, this default
 format is restored.
 
-Valid formats for floating point numbers are listed in the following table.
+Valid format options for floating point numbers are listed in the following
+table.
 
 @table @code
 @item short
@@ -3960,6 +3961,9 @@
 produce a more readable output with less data per page.
 @end table
 
+If @code{format} is called with multiple competing options, the most right one
+is used.  In case of an error the format remains unchanged.
+
 If called with one to three output arguments, and no inputs, return the current
 format, format spacing, and uppercase preference.