Re: Documentation for backend("fltk")

[Shai Ayal]

On Wed, Sep 16, 2009 at 8:33 AM, Michael D Godfrey
<address@hidden> wrote:
> I have been thinking about how to organize the documentation
> for the fltk_OpenGL plotting feature.   Below is the beginning of an
> updated plot.texi.  This indicates what I have in mind.  The main
> problem, if the organization below seems reasonable, is how to
> update the "Advanced Plotting" section.  One possibility is to
> start with the features that are the same in both fltk and gnuplot
> and then have 2 subsections which describe the features that
> are specific to each plotting system.  This may get a bit confusing.
>
> In any case, it would help if I could get reactions to this and
> suggestions for a better structure.
>
> First piece of plot.texi:
>
> @node Plotting
> @chapter Plotting
> @cindex plotting
> @cindex graphics
>
> @menu
> * Introduction::
> * Basic Plotting::
> * Graphics Handles::
> * Advanced Plotting::
> @end menu
>
> @node Introduction
> @section Introduction
>
> Earlier versions of Octave provided plotting through the use of
> gnuplot. This capability is still available.  But, a newer plotting
> capability is provided by access to OpenGL.  Which plotting system
> is used is controlled by the @code{backend} function.
>
> @code{backend("fltk")} selects the FLTK_OpenGL system, and
> @code{backend("gnuplot")} selects the gnuplot system.
> The two systems may be used selectively through the use of the
> @code{backend}
> property of the the graphics handle for each figure.  This is
> more fully explained in @ref{Graphics Handles}.
>
> @node Basic Plotting
> @section Basic Plotting
> =======================basic plotting as it is goes here==============
> @node Graphics Handles
> @section Graphics Handles
>
> Graphics handles provide a uniform means of storing and manipulating
> the properties of graphics objects.  The get and set commands are
> used to obtain and set graphics handle properties.
>
> A graphics handle property may be referenced by:
>
> get(h, "property")
>
> where h is a graphics handle and property is one of its properties.
>
> The allowed properties of a graphics handle may be displayed by:
> @code{get(h, "");}
>
> Thus, for example,
>
> @example
> @group
> h = figure();
> get(h, "");
> @end group
> @end example
>
> will display the allowed properties of the ``figure'' handle.
> And,
>
> @example
> @group
> aa=axes();
> get(aa,"");
> @end group
> @end example
>
> will display the allowed properties of the ``axes'' handle.
>
> The root figure has index 0.  Its properties may be displayed by:
>
> @code{get(0,"");}
>
> The available graphics handles are: @code{figure}, @code{axes},
> @code{line}, @code{text}, @code{patch},
> and @code{surface}.
> (@code{image} is still available, but is deprecated and will be removed.)
>
>
> @node Advanced Plotting
> @section Advanced Plotting
> ================Advanced Plotting with additional sections follows,
> but with handle stuff move up to the section above==============
>

It looks good to me, although (as you wrote in the documentation), all
the handle graphics stuff is in octave core and not coupled to any
specific backend such as gnuplot or fltk/open_gl
The backend specific sections should include specific
problems/features of a particular back end -- i.e. fltk backend does
not support printing yet, gnuplot might be slower for on-screen
graphics etc ....

Shai