From bug-request at octave dot org Tue Feb 8 12:17:05 2005 Subject: Plot Documentation Patch (again) From: Quentin Spencer To: bug at octave dot org Date: Tue, 08 Feb 2005 12:19:47 -0600 The patch I sent last week had a double node listing which caused makeinfo to fail when compiling. Here's a fixed version. --- plot.txi.~1.8.~ 2004-09-22 08:34:45.000000000 -0500 +++ plot.txi 2005-02-07 15:40:55.000000000 -0600 at @ -6,13 +6,17 @@ at chapter Plotting All of Octave's plotting functions use at code{gnuplot} to handle the -actual graphics. There are two low-level functions, at code{gplot} and +actual graphics. Most types of plots can be generated using the basic +plotting functions, which are patterned after the equivalent functions +in at sc{Matlab} dot The use of these functions is generally +straightforward, and is the preferred method for generating plots. +However, for users familiar with at code{gnuplot}, or for some +specialized applications where the basic commands are inadequate, +Octave also provides two low-level functions, at code{gplot} and at code{gsplot}, that behave almost exactly like the corresponding - at code{gnuplot} functions @code{plot} and @code{splot}. A number of -other higher level plotting functions, patterned after the graphics -functions found in at sc{Matlab} version 3.5, are also available. -These higher level functions are all implemented in terms of the two -low-level plotting functions. + at code{gnuplot} functions @code{plot} and @code{splot}. Also note that +some advanced at sc{Matlab} features from recent versions are not +implemented, such as handle-graphics and related functions. at menu * Two-Dimensional Plotting:: at @ -21,12 +25,113 @@ * Plot Annotations:: * Multiple Plots on One Page:: * Multiple Plot Windows:: + at c *Exporting Plots:: +* Low-Level plotting commands:: * Interaction with gnuplot:: at end menu at node Two-Dimensional Plotting at section Two-Dimensional Plotting +The at sc{Matlab}-style two-dimensional plotting commands are: + + at cindex plotting + at cindex graphics + + at DOCSTRING(plot) + + at DOCSTRING(hold) + + at DOCSTRING(ishold) + + at DOCSTRING(clearplot) + + at DOCSTRING(shg) + + at DOCSTRING(closeplot) + + at DOCSTRING(purge_tmp_files) + + at DOCSTRING(axis) + + at node Specialized Two-Dimensional Plots + at section Specialized Two-Dimensional Plots + + at DOCSTRING(bar) + + at DOCSTRING(contour) + + at DOCSTRING(hist) + + at DOCSTRING(loglog) + + at DOCSTRING(polar) + + at DOCSTRING(semilogx) + + at DOCSTRING(semilogy) + + at DOCSTRING(stairs) + + at DOCSTRING(errorbar) + + at DOCSTRING(loglogerr) + + at DOCSTRING(semilogxerr) + + at DOCSTRING(semilogyerr) + + at node Three-Dimensional Plotting + at section Three-Dimensional Plotting + +The at sc{Matlab}-style three-dimensional plotting commands are: + + at DOCSTRING(mesh) + + at DOCSTRING(meshgrid) + + at DOCSTRING(meshdom) + + at node Plot Annotations + at section Plot Annotations + + at DOCSTRING(grid) + + at DOCSTRING(title) + + at DOCSTRING(xlabel) + + at DOCSTRING(top_title) + + at node Multiple Plots on One Page + at section Multiple Plots on One Page + +The following functions all require a version of at code{gnuplot} that +supports the multiplot feature. + + at DOCSTRING(mplot) + + at DOCSTRING(multiplot) + + at DOCSTRING(oneplot) + + at DOCSTRING(plot_border) + + at DOCSTRING(subplot) + + at DOCSTRING(subwindow) + + at node Multiple Plot Windows + at section Multiple Plot Windows + + at DOCSTRING(figure) + + at c @node Exporting Plots + at c XXX FIXME XXX -- add info about getting paper copies of plots. + + at node Low-Level plotting commands + at section Low-Level plotting commands + at deffn {Command} gplot @var{ranges} @var{expression} @var{using} at var{title} @var{style} Generate a 2-dimensional plot. at @ -104,128 +209,6 @@ the border of the plot. at end deffn - at deffn {Command} gset options - at deffnx {Command} gshow options - at deffnx {Command} replot options -In addition to the basic plotting commands, the whole range of - at code{gset} and @code{gshow} commands from @code{gnuplot} are available, -as is at code{replot} dot - - at findex set - at findex show -Note that in Octave 2.0, the at code{set} and @code{show} commands were -renamed to at code{gset} and @code{gshow} in order to allow for -compatibility with the at sc{Matlab} graphics and GUI commands in a future -version of Octave. (For now, the old at code{set} and @code{show} -commands do work, but they print an annoying warning message to try to -get people to switch to using at code{gset} and @code{gshow}.) - -The at code{gset} and @code{gshow} commands allow you to set and show - at code{gnuplot} parameters. For more information about the @code{gset} -and at code{gshow} commands, see the documentation for @code{set} and - at code{show} in the @code{gnuplot} user's guide (also available on line -if you run at code{gnuplot} directly, instead of running it from Octave). - -The at code{replot} command allows you to force the plot to be -redisplayed. This is useful if you have changed something about the -plot, such as the title or axis labels. The at code{replot} command also -accepts the same arguments as at code{gplot} or @code{gsplot} (except for -data ranges) so you can add additional lines to existing plots. - -For example, - - at example -gset term tek40 -gset output "/dev/plotter" -gset title "sine with lines and cosine with impulses" -replot "sin (x) w l" - at end example - -will change the terminal type for plotting, add a title to the current -plot, add a graph of - at iftex - at tex -$\sin(x)$ - at end tex - at end iftex - at ifinfo -sin (x) - at end ifinfo -to the plot, and force the new plot to be -sent to the plot device. This last step is normally required in order -to update the plot. This default is reasonable for slow terminals or -hardcopy output devices because even when you are adding additional -lines with a replot command, gnuplot always redraws the entire plot, and -you probably don't want to have a completely new plot generated every -time something as minor as an axis label changes. - - at findex shg -The command at code{shg} is equivalent to executing @code{replot} without -any arguments. - at end deffn - - at DOCSTRING(automatic_replot) - -Note that NaN values in the plot data are automatically omitted, and -Inf values are converted to a very large value before calling gnuplot. - - at c XXX FIXME XXX -- add info about what to do to get plots on remote X - at c terminals. People often forget how to properly set DISPLAY and run - at c xhost. - - at c XXX FIXME XXX -- add info about getting paper copies of plots. - -The at sc{Matlab}-style two-dimensional plotting commands are: - - at cindex plotting - at cindex graphics - - at DOCSTRING(plot) - - at DOCSTRING(hold) - - at DOCSTRING(ishold) - - at DOCSTRING(clearplot) - - at DOCSTRING(shg) - - at DOCSTRING(closeplot) - - at DOCSTRING(purge_tmp_files) - - at DOCSTRING(axis) - - at node Specialized Two-Dimensional Plots - at section Specialized Two-Dimensional Plots - - at DOCSTRING(bar) - - at DOCSTRING(contour) - - at DOCSTRING(hist) - - at DOCSTRING(loglog) - - at DOCSTRING(polar) - - at DOCSTRING(semilogx) - - at DOCSTRING(semilogy) - - at DOCSTRING(stairs) - - at DOCSTRING(errorbar) - - at DOCSTRING(loglogerr) - - at DOCSTRING(semilogxerr) - - at DOCSTRING(semilogyerr) - - at node Three-Dimensional Plotting - at section Three-Dimensional Plotting - at deffn {Command} gsplot @var{ranges} @var{expression} @var{using} at var{title} @var{style} Generate a 3-dimensional plot. at @ -298,49 +281,75 @@ but not at code{rand (5, 30)}. at end deffn -The at sc{Matlab}-style three-dimensional plotting commands are: - - at DOCSTRING(mesh) - - at DOCSTRING(meshgrid) - - at DOCSTRING(meshdom) - - at node Plot Annotations - at section Plot Annotations - - at DOCSTRING(grid) - - at DOCSTRING(title) - - at DOCSTRING(bottom_title) - - at DOCSTRING(xlabel) + at deffn {Command} gset options + at deffnx {Command} gshow options + at deffnx {Command} replot options +In addition to the basic plotting commands, the whole range of + at code{gset} and @code{gshow} commands from @code{gnuplot} are available, +as is at code{replot} dot - at node Multiple Plots on One Page - at section Multiple Plots on One Page + at findex set + at findex show +Note that in Octave 2.0, the at code{set} and @code{show} commands were +renamed to at code{gset} and @code{gshow} in order to allow for +compatibility with the at sc{Matlab} graphics and GUI commands in a future +version of Octave. (For now, the old at code{set} and @code{show} +commands do work, but they print an annoying warning message to try to +get people to switch to using at code{gset} and @code{gshow}.) -The following functions all require a version of at code{gnuplot} that -supports the multiplot feature. +The at code{gset} and @code{gshow} commands allow you to set and show + at code{gnuplot} parameters. For more information about the @code{gset} +and at code{gshow} commands, see the documentation for @code{set} and + at code{show} in the @code{gnuplot} user's guide (also available on line +if you run at code{gnuplot} directly, instead of running it from Octave). - at DOCSTRING(mplot) +The at code{replot} command allows you to force the plot to be +redisplayed. This is useful if you have changed something about the +plot, such as the title or axis labels. The at code{replot} command also +accepts the same arguments as at code{gplot} or @code{gsplot} (except for +data ranges) so you can add additional lines to existing plots. - at DOCSTRING(multiplot) +For example, - at DOCSTRING(oneplot) + at example +gset term tek40 +gset output "/dev/plotter" +gset title "sine with lines and cosine with impulses" +replot "sin (x) w l" + at end example - at DOCSTRING(plot_border) +will change the terminal type for plotting, add a title to the current +plot, add a graph of + at iftex + at tex +$\sin(x)$ + at end tex + at end iftex + at ifinfo +sin (x) + at end ifinfo +to the plot, and force the new plot to be +sent to the plot device. This last step is normally required in order +to update the plot. This default is reasonable for slow terminals or +hardcopy output devices because even when you are adding additional +lines with a replot command, gnuplot always redraws the entire plot, and +you probably don't want to have a completely new plot generated every +time something as minor as an axis label changes. - at DOCSTRING(subplot) + at findex shg +The command at code{shg} is equivalent to executing @code{replot} without +any arguments. + at end deffn - at DOCSTRING(subwindow) + at DOCSTRING(automatic_replot) - at DOCSTRING(top_title) +Note that NaN values in the plot data are automatically omitted, and +Inf values are converted to a very large value before calling gnuplot. - at node Multiple Plot Windows - at section Multiple Plot Windows + at c XXX FIXME XXX -- add info about what to do to get plots on remote X + at c terminals. People often forget how to properly set DISPLAY and run + at c xhost. - at DOCSTRING(figure) at node Interaction with gnuplot at section Interaction with @code{gnuplot} ------------------------------------------------------------- Octave is freely available under the terms of the GNU GPL. Octave's home on the web: http://www.octave.org How to fund new projects: http://www.octave.org/funding.html Subscription information: http://www.octave.org/archive.html -------------------------------------------------------------