Mercurial > hg > octave-nkf
changeset 20029:0e585d3b8b9a
genpropdoc.m: Improve documentation on graphic object properties.
* genpropdoc.m: Improve documentation on graphic object properties.
author | Rik <rik@octave.org> |
---|---|
date | Sun, 22 Feb 2015 13:11:03 -0800 |
parents | b2c4f869ff7c |
children | bc3e6e96da81 |
files | doc/interpreter/genpropdoc.m |
diffstat | 1 files changed, 267 insertions(+), 245 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/interpreter/genpropdoc.m +++ b/doc/interpreter/genpropdoc.m @@ -17,13 +17,13 @@ ## -*- texinfo -*- ## @deftypefn {Function File} {@var{retval} =} genpropdoc (@var{OBJNAME}, @var{FILENAME}) ## -## Print FILENAME texinfo source file associated to OBJNAME objects. -## This function is meant to be run for generating octave -## documentation (see doc/interpreter/graphics_properties.mk). +## Print FILENAME texinfo source file associated to OBJNAME objects. This +## function is meant to be run for generating octave documentation +## (see doc/interpreter/graphics_properties.mk). ## -## All the hard coded documentation is written in getdoc -## function. See the comments in getdoc bellow for instruction on how -## to document a graphics property. +## All the hard coded documentation is written in getdoc function. See the +## comments in getdoc bellow for instruction on how to document a graphics +## property. ## ## @seealso{} ## @end deftypefn @@ -59,6 +59,7 @@ if (nargin == 2) fclose (fid); endif + endfunction function s = getdoc (objname, field, base) @@ -66,29 +67,27 @@ ## ## -"doc": string to be printed verbatim after being expanded ## through expand_doc function. Special keywords are: - ## "__objname__" further replaced by the current object name; - ## "__prop__" further replaced by the current property name; - ## "__modemsg__" further replaced by a message explaining that - ## the propmode will be toggled to "manual". + ## "__objname__" : replaced by the current object name; + ## "__prop__" : replaced by the current property name; + ## "__modemsg__" : replaced by a message explaining that + ## the propmode will be toggled to "manual". ## You may also cross reference properties using the label format - ## OBJNAMEPROPERTY, e.g, "@xref{XREFaxescolor, , axes color - ## property}." + ## OBJNAMEPROPERTY, e.g, "@xref{XREFaxescolor, , axes color property}." ## - ## -"valid": string that describes valid values for the - ## current property. Use "packopt" function to join options with - ## " | " separator and "markdef" to mark default among valid - ## values between curly braces. - ## If not provided, valid values for radio properties are - ## automatically retrieved using set function. + ## -"valid": string that describes valid values for the current property. + ## Use "packopt" function to join options with " | " separator + ## and "markdef" to mark default among valid values between curly braces. + ## If not provided, valid values for radio properties are automatically + ## retrieved using set function. ## - ## -"default": string. If not provided the default value is - ## automatically retrieved using get function. + ## -"default": string. If not provided the default value is automatically + ## retrieved using get function. ## ## -"printdefault": a boolean (def. true) that specifies whether the - ## default value should be printed. It is useful for properties - ## like root "screendepth" that default to screen dependant values. + ## default value should be printed. It is useful for properties + ## like root "screendepth" that default to screen dependant values. - packopt = @(c) strjoin (c, ' | '); + packopt = @(c) strjoin (c, " | "); markdef = @(s) ["@{" s "@}"]; ## Some generic templates: @@ -97,31 +96,29 @@ valid_string = "string"; valid_fcn = packopt ({"string", "function handle"}); valid_cellstring = packopt ({"string", "cell array of strings"}); - valid_2elvec = "two elements vector"; - valid_3elvec = "three elements vector"; - valid_4elvec = "four elements vector"; + valid_2elvec = "two-element vector"; + valid_3elvec = "three-element vector"; + valid_4elvec = "four-element vector"; valid_vecmat = packopt ({"vector", "matrix"}); valid_scalmat = packopt ({"scalar", "matrix"}); - doc_notimpl = "%s is not yet implemented for __objname__ \ -objects. __prop__ is unused."; + doc_notimpl = "%s is not yet implemented for __objname__ objects. \ +__prop__ is unused."; doc_unused = "__prop__ is unused."; - ## Initialize structure if (isfield (base, field)) s = base.(field); else - s = struct ("valid", "", "default", "", "doc", "", ... - "printdefault", true); + s = struct ("valid", "", "default", "", "doc", "", "printdefault", true); endif - ## Base properties: write generic documentation as it will, by - ## default, be included in the list of each graphics object. - ## If a given graphics object interprets the property differently - ## than most others, the doc will have to be rewritten for this object. + ## Base properties: Write generic documentation because it will be included + ## in the list of each graphics object. If a given graphics object + ## interprets the property differently than others, then the doc will have + ## to be rewritten for this object. if (strcmp (objname, "base")) - switch field + switch (field) case "beingdeleted" case "busyaction" case "buttondownfcn" @@ -135,20 +132,20 @@ clipped in its parent axes limits."; case "createfcn" - s.doc = "Callback functions to be executed right after \ -the __objname__ has been created. Those functions have to be set by \ -default using e.g. @code{set (0, \"default__objname__createfcn\", \ + s.doc = "Callback function executed immediately after __objname__ \ +has been created. Function is set by using default property on root object, \ +e.g., @code{set (0, \"default__objname__createfcn\", \ 'disp (\"__objname__ created!\")') }."; s.valid = valid_fcn; case "deletefcn" - s.doc = "Callback functions to be executed right before \ -the __objname__ is deleted."; + s.doc = "Callback function executed immediately before __objname__ \ +is deleted."; s.valid = valid_fcn; case "handlevisibility" s.doc = "If __prop__ is @qcode{\"off\"}, the __objname__'s \ -handle is not visible into its parent's children list."; +handle is not visible in its parent's \"children\" property."; case "hittest" case "interruptible" @@ -159,6 +156,7 @@ case "selected" case "selectionhighlight" case "tag" + s.doc = "A user-defined string to label the graphics object."; s.valid = valid_string; case "type" @@ -169,6 +167,9 @@ case "uicontextmenu" case "userdata" + s.doc = "User-defined data to associate with the graphics object."; + s.valid = "Any Octave data"; + case "visible" s.doc = "If __prop__ is @qcode{\"off\"}, the __objname__ is \ not rendered on screen."; @@ -176,7 +177,7 @@ ## Root properties: elseif (strcmp (objname, "root")) - switch field + switch (field) ## Overridden shared properties case {"beingdeleted", "busyaction", "buttondownfcn", ... "clipping", "createfcn", "deletefcn", "handlevisibility", ... @@ -198,52 +199,53 @@ s.valid = valid_handle; case "diary" - s.doc = "If __prop__ is @qcode{\"on\"}, the octave \ -command window session is saved to file. @xref{XREFrootdiaryfile, , \ -diaryfile property}."; - s.valid = valid_string; + s.doc = "If __prop__ is @qcode{\"on\"}, the Octave command window \ +session is saved to file. @xref{XREFrootdiaryfile, , @w{diaryfile property}}."; case "diaryfile" s.doc = "The name of the diary file. \ -@xref{XREFdiary, , diary function}."; +@xref{XREFdiary, , @w{diary function}}."; s.valid = valid_string; case "echo" - s.doc = "Control whether octave displays commands executed \ -from scripts. @xref{XREFecho, , echo function}."; + s.doc = "Control whether Octave displays commands executed from \ +scripts. @xref{XREFecho, , @w{echo function}}."; case "errormessage" - s.doc = "The last error message octave raised. \ -@xref{XREFlasterr, , lasterr function}."; + s.doc = "The last error message raised. \ +@xref{XREFlasterr, , @w{lasterr function}}."; s.valid = valid_string; case "fixedwidthfontname" s.valid = valid_string; case "format" - s.doc = "This property is a wrapper around @code{format} \ -function. @xref{XREFformat, , format function}."; + s.doc = "This property is a wrapper around the @code{format} function.\ + @xref{XREFformat, , @w{format function}}."; case "formatspacing" - s.doc = "This property is a wrapper around @code{format} \ -function. @xref{XREFformat, , format function}."; + s.doc = "This property is a wrapper around the @code{format} function.\ + @xref{XREFformat, , @w{format function}}."; case "language" s.valid = valid_string; case "monitorpositions" - s.valid = valid_4elvec; + s.doc = doc_unused; + s.printdefault = false; case "pointerlocation" + s.doc = doc_unused; s.valid = valid_2elvec; case "pointerwindow" + s.doc = doc_unused; s.valid = valid_handle; case "recursionlimit" - s.doc = "The maximum number of times a function can be \ -called recursively. @xref{XREFmax_recursion_depth, , \ -max_recursion_depth function}."; + s.doc = "The maximum number of times a function can be called \ +recursively. \ +@xref{XREFmax_recursion_depth, , @w{max_recursion_depth function}}."; s.valid = "double"; case "screendepth" @@ -259,16 +261,16 @@ s.printdefault = false; case "showhiddenhandles" - s.doc = "If __prop__ is @qcode{\"on\"}, all graphics objects \ -handle are visible in their parents' children list, regardless of \ -the value of their @code{handlevisibility} property."; + s.doc = "If __prop__ is @qcode{\"on\"}, all graphics objects handles \ +are visible in their parents' children list, regardless of the value of their \ +@code{handlevisibility} property."; case "units" endswitch ## Figure properties elseif (strcmp (objname, "figure")) - switch field + switch (field) ## Overridden shared properties case "clipping" s.doc = doc_unused; @@ -280,13 +282,12 @@ s.valid = valid_fcn; case "color" - s.doc = "Color of the figure background. @xref{Colors, , \ -colorspec}."; + s.doc = "Color of the figure background. \ +@xref{Colors, , colorspec}."; s.valid = valid_color; case "colormap" - s.doc = "A matrix containing the RGB color map for \ -the current axes."; + s.doc = "A matrix containing the RGB color map for the current axes."; s.valid = "N-by-3 matrix"; case "currentaxes" @@ -300,20 +301,19 @@ s.valid = valid_handle; case "currentpoint" - s.doc = "A 1-by-2 matrix which holds the coordinates of \ -the point over which the mouse pointer was when a mouse event \ -occurred. The x and y coordinates are in units defined by the \ -figures @qcode{\"units\"} property and their origin is the lower \ -left corner of the plotting area.\ -\n\nEvents which set @qcode{\"currentpoint\"} are\n\ + s.doc = "A 1-by-2 matrix which holds the coordinates of the point \ +over which the mouse pointer was when a mouse event occurred. The X and Y \ +coordinates are in units defined by the figure's @code{units} property \ +and their origin is the lower left corner of the plotting area.\n\ +\n\ +Events which set @code{currentpoint} are\n\ @table @asis\n\ @item A mouse button was pressed\n\ always\n\ @item A mouse button was released\n\ -only if the figures callback @qcode{\"windowbuttonupfcn\"} is defined\n\ -@item The pointer was moved while pressing mouse button (drag)\n\ - only if the figures callback @qcode{\"windowbuttonmotionfcn\"} is \ -defined \n\ +only if the figure's callback @code{windowbuttonupfcn} is defined\n\ +@item The pointer was moved while pressing the mouse button (drag)\n\ +only if the figure's callback @code{windowbuttonmotionfcn} is defined\n\ @end table"; s.valid = valid_2elvec; @@ -322,72 +322,82 @@ case "doublebuffer" case "filename" + s.doc = "The filename used when saving the plot figure"; + s.valid = valid_string; + case "integerhandle" + s.doc = "Assign the next lowest unused integer as the Figure number."; + case "inverthardcopy" case "keypressfcn" s.valid = valid_fcn; case "keyreleasefcn" - s.doc = "With @code{keypressfcn}, the keyboard callback \ -functions. These callback functions get called when a key is \ -pressed/released respectively. The functions are called with two \ -input arguments. The first argument holds the handle of the calling \ -figure. The second argument holds the event structure which has the \ -following members:\n\ + s.doc = "With @code{keypressfcn}, the keyboard callback functions. \ +These callback functions are called when a key is pressed/released \ +respectively. The functions are called with two input arguments. The first \ +argument holds the handle of the calling figure. The second argument holds \ +an event structure which has the following members:\n\ @table @code\n\ @item Character:\n\ The ASCII value of the key\n\ @item Key:\n\ -lowercase value of the key\n\ +Lowercase value of the key\n\ @item Modifier:\n\ -A cell array containing strings representing the modifiers pressed \ -with the key.\n\ +A cell array containing strings representing the modifiers pressed with the \ +key.\n\ @end table"; s.valid = valid_fcn; case "menubar" - case "mincolormap" + s.doc = "Control the display of the figure menu bar in the upper \ +left of the figure."; + case "name" - s.doc = "Name to be displayed in the figure title bar. If \ -__prop__ is empty, the title of the figure is \"figure\" followed \ -by the figure handle value."; + s.doc = "Name to be displayed in the figure title bar. The name is \ +displayed to the right of any title determined by the @code{numbertitle} \ +property."; s.valid = valid_string; case "nextplot" + case "numbertitle" + s.doc = "Display \"Figure\" followed by the numerical figure handle \ +value in the figure title bar."; + case "outerposition" s.valid = valid_4elvec; case "paperorientation" case "paperposition" - s.doc = "Vector @qcode{[x0 y0 width height]} defining the \ -position of the figure (in @code{paperunits} units) in the printed \ -page. __modemsg__."; + s.doc = "Vector @code{[x0 y0 width height]} defining the position of \ +the figure (in @code{paperunits} units) on the printed page.\ + __modemsg__."; s.valid = valid_4elvec; case "paperpositionmode" s.doc = "If __prop__ is set to @qcode{\"auto\"}, the \ -@qcode{\"paperposition\"} property is automatically computed: the \ -printed figure will have the same size as on-screen figure and will \ -be centered in the output page."; +@code{paperposition} property is automatically computed: the printed \ +figure will have the same size as the on-screen figure and will be centered \ +on the output page."; + case "papersize" - s.doc = "Vector @qcode{[width height]} defining the size of the \ -printing paper. Setting this property forces the @code{papertype} \ + s.doc = "Vector @code{[width height]} defining the size of the \ +paper for printing. Setting this property forces the @code{papertype} \ property to be set to @qcode{\"<custom>\"}."; s.valid = valid_2elvec; case "papertype" - s.doc = "Name of the paper to be used for printed output. \ + s.doc = "Name of the paper used for printed output. \ Setting __prop__ also changes @code{papersize} accordingly."; case "paperunits" - s.doc = "The unit used to compute the @code{paperposition} \ -property."; + s.doc = "The unit used to compute the @code{paperposition} property."; case "pointer" + s.doc = doc_unused; case "pointershapecdata" s.doc = doc_unused; - case "pointershapehotspot" s.doc = doc_unused; @@ -401,27 +411,31 @@ s.valid = valid_fcn; case "selectiontype" + s.doc = doc_unused; + case "toolbar" + s.doc = doc_unused; + case "units" s.doc = "The unit used to compute the @code{position} and \ @code{outerposition} properties."; + case "windowbuttondownfcn" s.doc = "@xref{XREFfigurewindowbuttonupfcn, , \ -windowbuttonupfcn property}."; +@w{windowbuttonupfcn property}}."; s.valid = valid_fcn; case "windowbuttonmotionfcn" s.doc = "@xref{XREFfigurewindowbuttonupfcn, , \ -windowbuttonupfcn property}."; +@w{windowbuttonupfcn property}}."; s.valid = valid_fcn; case "windowbuttonupfcn" s.doc = "With @code{windowbuttondownfcn} and \ @code{windowbuttonmotionfcn}, the mouse callback functions. These \ -callback functions get called when the mouse button is pressed, \ -dragged, and released respectively. When these callback functions \ -are called, the @code{currentpoint} property holds the current \ -coordinates of the cursor."; +callback functions are called when a mouse button is pressed, dragged, or \ +released respectively. When these callback functions are executed, the \ +@code{currentpoint} property holds the current coordinates of the cursor."; s.valid = valid_fcn; case "windowkeypressfcn" @@ -439,15 +453,16 @@ case "xdisplay" case "xvisual" case "xvisualmode" + case "__graphics_toolkit__" - s.doc = "The graphics toolkit that is used to render the \ -figure. @xref{XREFavailable_graphics_toolkits, , \ -available_graphics_toolkits function}."; + s.doc = "The graphics toolkit used to render the figure. \ +@xref{XREFavailable_graphics_toolkits, , \ +@w{available_graphics_toolkits function}}."; endswitch ## Axes properties elseif (strcmp (objname, "axes")) - switch field + switch (field) ## Overridden shared properties case "clipping" s.doc = doc_unused; @@ -479,60 +494,65 @@ case "cameraviewanglemode" case "clim" + s.doc = "Define the limits for the color axis of image children. \ +__modemsg__. @xref{XREFpcolor, , @w{pcolor function}}."; s.valid = valid_2elvec; - s.doc = "Define the limits for the color axis of image \ -children. __modemsg__. @xref{XREFpcolor, , pcolor function}."; case "climmode" + case "color" - s.doc = "Color of the axes background. @xref{Colors, , \ -colorspec}."; + s.doc = "Color of the axes background. @xref{Colors, , colorspec}."; s.valid = valid_color; case "colororder" - s.doc = "RGB values to be used by plot function for \ -automatic line coloring."; + s.doc = "RGB values used by plot function for automatic line \ +coloring."; s.valid = "N-by-3 RGB matrix"; case "currentpoint" - s.doc = "Matrix @qcode{[xf, yf, zf; xb, yb, zb]} which holds \ -the coordinates of the point over which the mouse pointer was when \ -the mouse button was pressed in axes data units. If a mouse \ -callback function is defined, @code{currentpoint} holds the \ -pointer coordinates at the time the mouse button was pressed. For \ -3D plots, the first row of the returned matrix specifies the point \ -nearest to the current camera position and the second rows the \ -furthest point. The two points forms a line which is perpendicular \ -to the screen."; + s.doc = "Matrix @code{[xf, yf, zf; xb, yb, zb]} which holds the \ +coordinates (in axes data units) of the point over which the mouse pointer \ +was when the mouse button was pressed. If a mouse callback function is \ +defined, @code{currentpoint} holds the pointer coordinates at the time \ +the mouse button was pressed. For 3-D plots, the first row of the returned \ +matrix specifies the point nearest to the current camera position and the \ +second row the furthest point. The two points forms a line which is \ +perpendicular to the screen."; s.valid = "2-by-3 matrix"; case "dataaspectratio" s.doc = "Specify the relative height and width of the data \ -displayed in the axes. Setting @code{dataaspectratio} to @samp{[1, \ -2]} causes the length of one unit as displayed on the y-axis to be \ -the same as the length of 2 units on the x-axis. __modemsg__."; +displayed in the axes. Setting @code{dataaspectratio} to \ +@w{@code{[1, 2]}} causes the length of one unit as displayed on the x-axis \ +to be the same as the length of 2 units on the y-axis. __modemsg__."; s.valid = valid_3elvec; case "dataaspectratiomode" case "drawmode" case "fontangle" case "fontname" - s.doc = "Name of the font to be used for axes annotations."; + s.doc = "Name of the font used for axes annotations."; s.valid = valid_string; case "fontsize" - s.doc = "Size of the font to be used for axes annotations. \ -@xref{XREFaxesfontunits, , fontunits property}."; + s.doc = "Size of the font used for axes annotations. \ +@xref{XREFaxesfontunits, , @w{fontunits property}}."; s.valid = "scalar"; case "fontunits" s.doc = "Unit used to interpret @code{fontsize} property."; case "fontweight" + case "gridlinestyle" case "interpreter" + case "layer" + s.doc = "Control whether the axes is drawn below child graphics \ +objects (ticks, labels, etc. covered by plotted objects) or above."; + case "linestyleorder" + case "linewidth" case "minorgridlinestyle" case "mousewheelzoom" @@ -541,32 +561,42 @@ case "nextplot" case "outerposition" - s.doc = "Specify the position of the plot, including titles, \ -axes and legend. The four elements of the vector are the \ + s.doc = "Specify the position of the plot including titles, \ +axes, and legend. The four elements of the vector are the \ coordinates of the lower left corner and width and height of the \ plot, in units normalized to the width and height of the plot \ -window. For example, @qcode{[0.2, 0.3, 0.4, 0.5]} sets the lower \ +window. For example, @code{[0.2, 0.3, 0.4, 0.5]} sets the lower \ left corner of the axes at @math{(0.2, 0.3)} and the width and \ -height to be 0.4 and 0.5 respectively. @xref{XREFaxesposition, , position property}."; +height to be 0.4 and 0.5 respectively. \ +@xref{XREFaxesposition, , @w{position property}}."; s.valid = valid_4elvec; case "plotboxaspectratio" case "plotboxaspectratiomode" case "position" - s.doc = "Specify the position of the plot, excluding titles, \ -axes and legend. The four elements of the vector are the \ + s.doc = "Specify the position of the plot excluding titles, \ +axes, and legend. The four elements of the vector are the \ coordinates of the lower left corner and width and height of the \ plot, in units normalized to the width and height of the plot \ -window. For example, @qcode{[0.2, 0.3, 0.4, 0.5]} sets the lower \ +window. For example, @code{[0.2, 0.3, 0.4, 0.5]} sets the lower \ left corner of the axes at @math{(0.2, 0.3)} and the width and \ -height to be 0.4 and 0.5 respectively. @xref{XREFaxesouterposition, , \ -outerposition property}."; +height to be 0.4 and 0.5 respectively. \ +@xref{XREFaxesouterposition, , @w{outerposition property}}."; s.valid = valid_4elvec; case "projection" + case "tickdir" + s.doc = "Control whether axes tick marks project \"in\" to the plot \ +box or \"out\"."; + case "tickdirmode" + case "ticklength" + s.doc = "Two-element vector @code{[2Dlen 3Dlen]} specifying the \ +length of the tickmarks relative to the longest visible axis."; + s.valid = valid_2elvec; + case "tightinset" case "title" s.doc = "Graphics handle of the title text object."; @@ -574,14 +604,14 @@ case "units" case "view" - s.doc = "Specify the view point for three-dimensional plots"; + s.doc = "Two-element vector @code{[azimuth elevation]} specifying \ +the viewpoint for three-dimensional plots"; s.valid = valid_2elvec; case "xaxislocation" case "xcolor" s.doc = "Color of the x-axis. @xref{Colors, , colorspec}."; - s.valid = packopt ({markdef(valid_color), ... - "@qcode{\"none\"}"}); + s.valid = packopt ({markdef(valid_color), "@qcode{\"none\"}"}); case "xdir" case "xgrid" @@ -592,8 +622,8 @@ s.valid = valid_handle; case "xlim" - s.doc = "Specify the limits for x-axis. __modemsg__. \ -@xref{XREFxlim, , xlim function}."; + s.doc = "Two-element vector @code{[xmin xmax]} specifying the limits \ +for the x-axis. __modemsg__. @xref{XREFxlim, , @w{xlim function}}."; s.valid = valid_2elvec; case "xlimmode" @@ -615,8 +645,7 @@ case "yaxislocation" case "ycolor" s.doc = "Color of the y-axis. @xref{Colors, , colorspec}."; - s.valid = packopt ({markdef(valid_color), ... - "@qcode{\"none\"}"}); + s.valid = packopt ({markdef(valid_color), "@qcode{\"none\"}"}); case "ydir" case "ygrid" @@ -627,8 +656,8 @@ s.valid = valid_handle; case "ylim" - s.doc = "Specify the limits for y-axis. __modemsg__. \ -@xref{XREFylim, , ylim function}."; + s.doc = "Two-element vector @code{[ymin ymax]} specifying the limits \ +for the y-axis. __modemsg__. @xref{XREFylim, , @w{ylim function}}."; s.valid = valid_2elvec; case "ylimmode" @@ -649,8 +678,7 @@ case "ytickmode" case "zcolor" s.doc = "Color of the z-axis. @xref{Colors, , colorspec}."; - s.valid = packopt ({markdef(valid_color), ... - "@qcode{\"none\"}"}); + s.valid = packopt ({markdef(valid_color), "@qcode{\"none\"}"}); case "zdir" case "zgrid" @@ -661,8 +689,8 @@ s.valid = valid_handle; case "zlim" - s.doc = "Specify the limits for z-axis. __modemsg__. \ -@xref{XREFzlim, , zlim function}."; + s.doc = "Two-element vector @code{[zmin zmaz]} specifying the limits \ +for the z-axis. __modemsg__. @xref{XREFzlim, , @w{zlim function}}."; s.valid = valid_2elvec; case "zlimmode" @@ -685,20 +713,18 @@ ## Line properties elseif (strcmp (objname, "line")) - switch field + switch (field) ## Overridden shared properties case "children" s.doc = doc_unused; ## Specific properties case "color" - s.doc = "Color of the line object. @xref{Colors, , \ -colorspec}."; + s.doc = "Color of the line object. @xref{Colors, , colorspec}."; s.valid = valid_color; case "displayname" - s.doc = "The text of the legend entry corresponding to this \ -line."; + s.doc = "Text for the legend entry corresponding to this line."; s.valid = valid_cellstring; case "erasemode" @@ -709,26 +735,26 @@ s.doc = "@xref{Line Styles}."; case "linewidth" - s.doc = "Width in points of the line object."; + s.doc = "Width of the line object measured in points."; case "marker" - s.doc = "The shape of the marker to be used. @xref{Marker \ -Styles}."; + s.doc = "Shape of the marker for each data point. \ +@xref{Marker Styles}."; case "markeredgecolor" - s.doc = "Color of the edge of the markers. If set \ -@qcode{\"auto\"}, the markers edges have the same color as the line. If \ -set @qcode{\"none\"}, the markers edges are not displayed. This property \ -can also be set to any color. @xref{Colors, , colorspec}."; + s.doc = "Color of the edge of the markers. When set to \ +@qcode{\"auto\"}, the marker edges have the same color as the line. If set \ +to @qcode{\"none\"}, no marker edges are displayed. This property can also \ +be set to any color. @xref{Colors, , colorspec}."; case "markerfacecolor" - s.doc = "Color of the face of the markers. If set \ -@qcode{\"auto\"}, the markers faces have the same color as the line. If \ -set @qcode{\"none\"}, the markers faces are not displayed. This property \ + s.doc = "Color of the face of the markers. When set to \ +@qcode{\"auto\"}, the marker faces have the same color as the line. If set \ +to @qcode{\"none\"}, the marker faces are not displayed. This property \ can also be set to any color. @xref{Colors, , colorspec}."; case "markersize" - s.doc = "Size of the markers in points."; + s.doc = "Size of the markers measured in points."; s.valid = "scalar"; case "xdata" @@ -736,33 +762,33 @@ s.valid = "vector"; case "xdatasource" + s.doc = "Name of a vector in the current base workspace to use as \ +x data."; s.valid = valid_string; - s.doc = "Name of the vector in the current base workspace \ -that should be used as x data."; case "ydata" s.doc = "Vector of y data to be plotted."; s.valid = "vector"; case "ydatasource" + s.doc = "Name of a vector in the current base workspace to use as \ +y data."; s.valid = valid_string; - s.doc = "Name of the vector in the current base workspace \ -that should be used as y data."; case "zdata" s.doc = "Vector of z data to be plotted."; s.valid = "vector"; case "zdatasource" + s.doc = "Name of a vector in the current base workspace to use as \ +z data."; s.valid = valid_string; - s.doc = "Name of the vector in the current base workspace \ -that should be used as z data."; endswitch ## Text properties elseif (strcmp (objname, "text")) - switch field + switch (field) ## Overridden shared properties case "children" s.doc = doc_unused; @@ -773,7 +799,7 @@ s.valid = valid_color; case "color" - s.doc = "Color of the text. @xref{Colors, ,colorspec}. "; + s.doc = "Color of the text. @xref{Colors, ,colorspec}."; s.valid = valid_color; case "displayname" @@ -795,15 +821,15 @@ s.valid = valid_string; case "fontsize" - s.doc = "The font size of the text."; + s.doc = "The font size of the text as measured in \ +@code{fontunits}."; s.valid = "scalar"; case "fontunits" - s.doc = "The units used to interpret @code{fontsize} \ -property."; + s.doc = "The units used to interpret @code{fontsize} property."; case "fontweight" - s.doc = "Flag whether the font is bold, etc."; + s.doc = "Control variant of base font used: bold, light, normal, etc."; case "horizontalalignment" case "interpreter" @@ -819,9 +845,9 @@ s.valid = "scalar"; case "position" - s.doc = "Vector @qcode{[X0 Y0 Z0]} where X0, Y0 and Z0 \ -indicate the position of the text anchor as defined by \ -@code{verticalalignment} and @code{horizontalalignment}."; + s.doc = "Vector @code{[X0 Y0 Z0]} where X0, Y0 and Z0 indicate the \ +position of the text anchor as defined by @code{verticalalignment} and \ +@code{horizontalalignment}."; s.valid = valid_4elvec; case "rotation" @@ -839,7 +865,7 @@ ## Image properties elseif (strcmp (objname, "image")) - switch field + switch (field) ## Overridden shared properties case "children" s.doc = doc_unused; @@ -857,32 +883,33 @@ case "cdatamapping" case "displayname" - s.doc = "The text of the legend entry corresponding to this \ -image."; + s.doc = "Text for the legend entry corresponding to this image."; s.valid = valid_cellstring; case "erasemode" s.doc = doc_unused; case "xdata" - s.doc = "Two element vector @qcode{[xmin xmax]} specifying the x \ -coordinates of the first and last columns of the image. \ -\n\nSetting @code{xdata} empty matrix makes octave automatically \ -affect it the value @qcode{[1 columns(image)]}."; + s.doc = "Two-element vector @code{[xmin xmax]} specifying the x \ +coordinates of the first and last columns of the image.\n\ +\n\ +Setting @code{xdata} to the empty matrix ([]) will restore the default value \ +of @code{[1 columns(image)]}."; s.valid = valid_2elvec; case "ydata" - s.doc = "Vector @qcode{[ymin ymax]} specifying the y \ -coordinates of the first and last columns of the image. \ -\n\nSetting @code{ydata} empty matrix makes octave automatically \ -affect it the value @qcode{[1 rows(image)]}."; + s.doc = "Two-element vector @code{[ymin ymax]} specifying the y \ +coordinates of the first and last rows of the image.\n\ +\n\ +Setting @code{ydata} to the empty matrix ([]) will restore the default value \ +of @code{[1 rows(image)]}."; s.valid = valid_2elvec; endswitch ## Surface properties elseif (strcmp (objname, "surface")) - switch field + switch (field) ## Overridden shared properties case "children" s.doc = doc_unused; @@ -910,8 +937,7 @@ s.doc = sprintf (doc_notimpl, "Light"); case "displayname" - s.doc = "The text of the legend entry corresponding to this \ -surface."; + s.doc = "Text for the legend entry corresponding to this surface."; case "edgealpha" s.doc = sprintf (doc_notimpl, "Transparency"); @@ -936,23 +962,22 @@ s.doc = "@xref{Line Styles}."; case "linewidth" - s.doc = "@xref{XREFlinelinewidth, , line linewidth \ -property}."; + s.doc = "@xref{XREFlinelinewidth, , @w{line linewidth property}}."; case "marker" s.doc = "@xref{Marker Styles}."; case "markeredgecolor" - s.doc = "@xref{XREFlinemarkeredgecolor, , line \ -markeredgecolor property}."; + s.doc = "@xref{XREFlinemarkeredgecolor, , \ +@w{line markeredgecolor property}}."; case "markerfacecolor" - s.doc = "@xref{XREFlinemarkerfacecolor, , line \ -markerfacecolor property}."; + s.doc = "@xref{XREFlinemarkerfacecolor, , \ +@w{line markerfacecolor property}}."; case "markersize" - s.doc = "@xref{XREFlinemarkersize, , line \ -markersize property}."; + s.doc = "@xref{XREFlinemarkersize, , \ +@w{line markersize property}}."; s.valid = "scalar"; case "meshstyle" @@ -983,7 +1008,7 @@ ## Patch properties elseif (strcmp (objname, "patch")) - switch field + switch (field) ## Overridden shared properties case "children" s.doc = doc_unused; @@ -1001,13 +1026,16 @@ case "cdata" s.doc = "Data defining the patch object color.\n\ -Patch color can be defined for faces or for vertices. \n\n\ -If @code{cdata} is a scalar index into the current colormap or a RGB \ -triplet, it defines the color of all faces. \n\n\ -If @code{cdata} is a N-by-1 vector of indices or a N-by-3 (RGB) \ -matrix, it defines the color of each one of the N faces.\n\n\ -If @code{cdata} is a N-by-M or a N-by-M-by-3 (RGB) \ -matrix, it defines the color all vertices."; +Patch color can be defined for faces or for vertices.\n\ +\n\ +If @code{cdata} is a scalar index into the current colormap or a RGB triplet, \ +it defines the color of all faces.\n\ +\n\ +If @code{cdata} is an N-by-1 vector of indices or an N-by-3 (RGB) matrix, \ +it defines the color of each one of the N faces.\n\ +\n\ +If @code{cdata} is an N-by-M or an N-by-M-by-3 (RGB) matrix, \ +it defines the color at each vertex."; s.valid = valid_scalmat; case "diffusestrength" @@ -1015,8 +1043,8 @@ s.valid = "scalar"; case "displayname" - s.doc = "The text of the legend entry corresponding to this \ -patch."; + s.doc = "Text of the legend entry corresponding to this patch."; + case "edgealpha" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = valid_scalmat; @@ -1036,8 +1064,8 @@ ## Don't provide a default value, and mark colorspec with ## braces, this forces the default rgb triplet to be displayed s.valid = packopt ({markdef(valid_color), ... + "@qcode{\"none\"}", ... "@qcode{\"flat\"}", ... - "@qcode{\"none\"}", ... "@qcode{\"interp\"}"}); case "facelighting" @@ -1058,19 +1086,18 @@ case "linestyle" case "linewidth" case "marker" - s.doc = "@xref{XREFlinemarker, , line marker property}."; + s.doc = "@xref{XREFlinemarker, , @w{line marker property}}."; case "markeredgecolor" - s.doc = "@xref{XREFlinemarkeredgecolor, , line \ -markeredgecolor property}."; + s.doc = "@xref{XREFlinemarkeredgecolor, , \ +@w{line markeredgecolor property}}."; case "markerfacecolor" - s.doc = "@xref{XREFlinemarkerfacecolor, , line \ -markerfacecolor property}."; + s.doc = "@xref{XREFlinemarkerfacecolor, , \ +@w{line markerfacecolor property}}."; case "markersize" - s.doc = "@xref{XREFlinemarkersize, , line \ -markersize property}."; + s.doc = "@xref{XREFlinemarkersize, , @w{line markersize property}}."; s.valid = "scalar"; case "normalmode" @@ -1122,17 +1149,14 @@ function s = getstructure (objname, base = []) hf = []; if (! strcmp (objname, "root")) - ## Use an improbable figure number to avoid ishandle to return - ## true for 1 + ## Use an improbable number to avoid ishandle to return true for 1 hf = figure (2265465, "visible", "off"); endif - ## Build a default object to extract its properties list and default - ## values. + ## Build a default object to extract its properties list and default values. if (strcmp (objname, "base")) - ## Base properties are extracted from hggroup that only have 2 - ## additional regular (non-hidden) properties, "displayname" and - ## "erasemode". + ## Base properties are extracted from hggroup that only have 2 additional + ## regular (non-hidden) properties, "displayname" and "erasemode". h = hggroup (); elseif (strcmp (objname, "root")) h = 0; @@ -1164,12 +1188,11 @@ ## Extract the valid values that are not hard coded in getdoc if (! val.isreadonly && isempty (val.valid)) val.valid = sprop.(field); - if (! isempty (val.valid) && - iscellstr (val.valid)) + if (! isempty (val.valid) && iscellstr (val.valid)) ## Add double quotes around string radio properties val.valid = cellfun (@(s) ["@qcode{\"" s "\"}"], val.valid, "uniformoutput", false); - val.valid = strjoin (val.valid, ' | '); + val.valid = strjoin (val.valid, " | "); endif endif @@ -1187,6 +1210,7 @@ if (isfigure (hf)) close (hf) endif + endfunction function def = getdefault (h, objname, field) @@ -1199,10 +1223,9 @@ def = ""; else if (ischar (def)) - def = ["@qcode{\"" def "\"}"]; + def = ['@qcode{"' def '"}']; else - if ((isvector (def) && numel (def) < 5) || - isempty (def)) + if ((isvector (def) && numel (def) < 5) || isempty (def)) ## Use disp to print the default value for short vectors and ## empty values str = disp (def); @@ -1225,12 +1248,12 @@ def = ["@code{" def "}"]; else - args = arrayfun (@(x) num2str (x), size (def), - "uniformoutput", false); + args = arrayfun (@(x) num2str (x), size (def), "uniformoutput", false); def = [strjoin(args, "-by-") " " class(def)]; endif endif endif + endfunction function str = printdoc (objname, obj) @@ -1241,14 +1264,12 @@ ## File header and begining of properties table str = [warn_autogen() "\n\n@table @asis"]; - for ii = 1:nf field = fields{ii}; str = sprintf ("%s\n\n", str); ## @anchor: cross reference using XREFobjnamefield label - ## Concept index: call info from octave with - ## 'doc ("objname field")' + ## Concept index: call info from octave with 'doc ("objname field")' str = sprintf ("%s@anchor{XREF%s%s}\n@cindex %s %s\n", str, objname, field, objname, field); @@ -1277,6 +1298,7 @@ ## End of properties table str = sprintf ("%s\n@end table", str); + endfunction function str = warn_autogen ()