# HG changeset patch
# User Pantxo Diribarne <pantxo.diribarne@gmail.com>
# Date 1536327002 -7200
#      Fri Sep 07 15:30:02 2018 +0200
# Node ID 9fbb3da5698c331351bfa0fc9fdcee510b43fc31
# Parent  d19dfcc862d47b4ea02615f2b82b1ca09e92c3a8
Document that high level graphics functions redefine axes properties (bug #49400)

* plot.txi: Document that high level graphics functions redefine axes
   properties. Replace bad example using an error by the proper way of
   retrieving object properties.   

diff -r d19dfcc862d4 -r 9fbb3da5698c doc/interpreter/plot.txi
--- a/doc/interpreter/plot.txi	Wed Sep 05 22:33:34 2018 +0200
+++ b/doc/interpreter/plot.txi	Fri Sep 07 15:30:02 2018 +0200
@@ -264,7 +264,10 @@
 
 The axis function may be used to change the axis limits of an existing
 plot and various other axis properties, such as the aspect ratio and the
-appearance of tic marks.
+appearance of tic marks.  By default, high level plotting functions such as
+@code{plot} reset axes properties so any customization, using with @code{axis},
+@code{xlim}, etc, should happen after the plot is done or alternatively after
+calling the @ref{XREFhold, ,hold function}.
 
 @DOCSTRING(axis)
 
@@ -661,10 +664,11 @@
 @DOCSTRING(refresh)
 
 Normally, high-level plot functions like @code{plot} or @code{mesh} call
-@code{newplot} to initialize the state of the current axes so that the
-next plot is drawn in a blank window with default property settings.  To
-have two plots superimposed over one another, use the @code{hold}
-function.  For example,
+@code{newplot} to determine wether the state of the target axes should be
+initialized (the default) or if subsequent plots should be drawn on top of
+previous ones.  To have two plots drawn over one another, use the @code{hold}
+function or manually change the axes @ref{XREFaxesnextplot, ,nextplot} property.
+For example,
 
 @example
 @group
@@ -1191,13 +1195,6 @@
 more specific test functions return true only if the argument is both a
 graphics handle and of the correct type (figure, axes, specified object type).
 
-The @code{whos} function can be used to show the object type of each currently
-defined graphics handle.  (Note: this is not true today, but it is, I hope,
-considered an error in whos.  It may be better to have whos just show
-graphics_handle as the class, and provide a new function which, given a
-graphics handle, returns its object type.  This could generalize the ishandle()
-functions and, in fact, replace them.)
-
 The @code{get} and @code{set} commands are used to obtain and set the values of
 properties of graphics objects.  In addition, the @code{get} command may be
 used to obtain property names.
@@ -1209,52 +1206,36 @@
 get (h, "type")
 @end example
 
-The properties and their current values are returned by @code{get (h)}
-where h is a handle of a graphics object.  If only the names of the
-allowed properties are wanted they may be displayed by:
-@code{get (h, "")}.
+The properties and their current values may be obtained in the form of a
+structure using @code{s = get (h)}, where @code{h} is the handle of a graphics
+object.  If only the names of the properties and the allowed values (for radio
+properties only) are wanted, one may use @code{set (h)}.
 
 Thus, for example:
 
-@smallexample
+@example
 h = figure ();
 get (h, "type")
-ans = figure
-get (h, "");
-error: get: ambiguous figure property name ; possible matches:
-
-__gl_extensions__      dockcontrols           renderer
-__gl_renderer__        doublebuffer           renderermode
-__gl_vendor__          filename               resize
-__gl_version__         graphicssmoothing      resizefcn
-__graphics_toolkit__   handlevisibility       selected
-__guidata__            hittest                selectionhighlight
-__modified__           integerhandle          selectiontype
-__mouse_mode__         interruptible          sizechangedfcn
-__myhandle__           inverthardcopy         tag
-__pan_mode__           keypressfcn            toolbar
-__plot_stream__        keyreleasefcn          type
-__rotate_mode__        menubar                uicontextmenu
-__zoom_mode__          mincolormap            units
-alphamap               name                   userdata
-beingdeleted           nextplot               visible
-busyaction             numbertitle            windowbuttondownfcn
-buttondownfcn          outerposition          windowbuttonmotionfcn
-children               paperorientation       windowbuttonupfcn
-clipping               paperposition          windowkeypressfcn
-closerequestfcn        paperpositionmode      windowkeyreleasefcn
-color                  papersize              windowscrollwheelfcn
-colormap               papertype              windowstyle
-createfcn              paperunits             wvisual
-currentaxes            parent                 wvisualmode
-currentcharacter       pointer                xdisplay
-currentobject          pointershapecdata      xvisual
-currentpoint           pointershapehotspot    xvisualmode
-deletefcn              position
-@end smallexample
-
-The properties of the root figure may be displayed by:
-@code{get (groot, "")}.
+@result{} ans = figure
+set (h)
+@result{}
+        alphamap:
+        beingdeleted:  [ @{off@} | on ]
+        busyaction:  [ cancel | @{queue@} ]
+        buttondownfcn:
+        clipping:  [ off | @{on@} ]
+        closerequestfcn:
+        color:
+        colormap:
+        createfcn:
+        currentaxes:
+        deletefcn:
+        dockcontrols:  [ @{off@} | on ]
+        filename:
+        graphicssmoothing:  [ off | @{on@} ]
+        handlevisibility:  [ callback | off | @{on@} ]
+        ...
+@end example
 
 The uses of @code{get} and @code{set} are further explained in
 @ref{XREFget,,get}, @ref{XREFset,,set}.
@@ -1739,6 +1720,25 @@
 object.  To quickly remove all user-defined defaults use the @code{reset}
 function.
 
+By default, high level plotting functions such as @code{plot} reset and
+redefine axes properties independently from the defaults. An example of such
+property is the axes @code{box} property: it is set @code{on} by high level 2D
+graphics functions whatever the @code{"defaultaxesbox"}.  Use the @code{hold}
+function to prevent this behavior:
+
+@example
+@group
+set (groot, "defaultaxesbox", "off");
+subplot (2, 1, 1);
+plot (1:10)
+title ("Box is on anyway")
+subplot (2, 1, 2);
+hold on
+plot (1:10)
+title ("Box is off")
+@end group
+@end example
+
 @DOCSTRING(reset)
 
 Getting the @qcode{"default"} property of an object returns a list of
@@ -2674,4 +2674,3 @@
 @file{@var{octave-home}\bin\opengl32.dll}
 @*where @var{octave-home} is the directory in which Octave is installed (the
 default is @file{C:\Octave\Octave-@var{version}}).
-
