Mercurial > octave-nkf
view doc/interpreter/genpropdoc.m @ 19291:1f2a16d41ba2
Automatically generate graphics properties documentation (bug #42536)
* doc/interpreter/Makefile.am: include new graphics_poperties.mk file and
add $(GRAPH_PROP_TEXI_SRC) to the list of built texinfos.
* doc/interpreter/graphics_poperties.mk: new file. Define the list of
built texi sources for graphics properties. Write build rules using
genpropdoc.m.
* doc/interpreter/plot.txi: remove property tables and include built
texi sources.
* doc/interpreter/genpropdoc.m: new file to generate the properties
documentation.
author | Pantxo Diribarne <pantxo.diribarne@gmail.com> |
---|---|
date | Fri, 17 Oct 2014 09:29:10 +0200 |
parents | |
children | 346b20b2c2ff |
line wrap: on
line source
## Copyright (C) 2014 Pantxo Diribarne ## ## This program is free software; you can redistribute it and/or modify it ## under the terms of the GNU General Public License as published by ## the Free Software Foundation; either version 3 of the License, or ## (at your option) any later version. ## ## This program is distributed in the hope that it will be useful, ## but WITHOUT ANY WARRANTY; without even the implied warranty of ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ## GNU General Public License for more details. ## ## You should have received a copy of the GNU General Public License ## along with this program. If not, see ## <http://www.gnu.org/licenses/>. ## -*- 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). ## ## 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 function genpropdoc (objname, fname) objnames = {"root", "figure", "axes", "line", ... "text", "image", "patch", "surface"}; ## Base properties base = getstructure ("base"); ## Object properties if (any (strcmp (objname, objnames))) obj = getstructure (objname, base); else error ("genpropdoc: unknown object %s", objname); endif ## Docstring str = printdoc (objname, obj); fid = fopen (fname, "w+"); if (fid < 0) error ("genpropdoc: couldn't open %s.", fname); endif fprintf (fid, str); fclose (fid); endfunction function s = getdoc (objname, field, base) ## Properties are represented by a struct with fields : ## ## -"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". ## You may also cross reference properties using the label format ## 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. ## ## -"default": string. If not provided the default value is ## automatically retrieved using get function. ## ## -"printdefault": a boolean (def. true) that sepcifies whether the ## default value should be printed. It is usefull for properties ## like root "screendepth" that default to screen dependant values. packopt = @(c) strjoin (c, ' | '); markdef = @(s) ["@{" s "@}"]; ## Some generic templates: valid_color = "colorspec"; valid_handle = "graphics handle"; 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_vecmat = packopt ({"vector", "matrix"}); valid_scalmat = packopt ({"scalar", "matrix"}); 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); 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. if (strcmp (objname, "base")) switch field case "beingdeleted" case "busyaction" case "buttondownfcn" s.valid = valid_fcn; case "children" s.doc = "Graphics handles of the __objname__'s children."; s.valid = "vector of graphics handles"; case "clipping" s.doc = "If __prop__ is @qcode{\"on\"}, the __objname__ is \ 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\", \ 'disp (\"__objname__ created!\")') }."; s.valid = valid_fcn; case "deletefcn" s.doc = "Callback functions to be executed right before \ the __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."; case "hittest" case "interruptible" case "parent" s.doc = "Handle of the parent graphics object."; s.valid = valid_handle; case "selected" case "selectionhighlight" case "tag" s.valid = valid_string; case "type" s.doc = "Class name of the graphics object. __prop__ is \ always @qcode{\"__objname__\"}"; s.valid = valid_string; s.printdefault = false; case "uicontextmenu" case "userdata" case "visible" s.doc = "If __prop__ is @qcode{\"off\"}, the __objname__ is \ not rendered on screen."; endswitch ## Root properties: elseif (strcmp (objname, "root")) switch field ## Overridden shared properties case {"beingdeleted", "busyaction", "buttondownfcn", ... "clipping", "createfcn", "deletefcn", "handlevisibility", ... "hittest", "interruptible", "selected", ... "selectionhighlight", "uicontextmenu", "visible"} s.doc = doc_unused; case "parent" s.doc = "Root figure has no parent graphics object. __prop__ \ is always empty."; ## Specific properties case "callbackobject" s.valid = valid_handle; case "commandwindowsize" case "currentfigure" s.doc = "Graphics handle of the current figure."; 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; case "diaryfile" s.doc = "The name of the diary file. \ @xref{XREFdiary, , diary function}."; s.valid = valid_string; case "echo" s.doc = "Control whether octave displays commands executed \ from scripts. @xref{XREFecho, , echo function}."; case "errormessage" s.doc = "The last error message octave raised. \ @xref{XREFlasterr, , 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}."; case "formatspacing" s. doc = "This property is a wrapper around @code{format} \ function. @xref{XREFformat, , format function}."; case "language" s.valid = valid_string; case "monitorpositions" s.valid = valid_4elvec; case "pointerlocation" s.valid = valid_2elvec; case "pointerwindow" 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.valid = "double"; case "screendepth" s.valid = "double"; s.printdefault = false; case "screenpixelsperinch" s.valid = "double"; s.printdefault = false; case "screensize" s.valid = valid_4elvec; 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."; case "units" endswitch ## Figure properties elseif (strcmp (objname, "figure")) switch field ## Overridden shared properties case "clipping" s.doc = doc_unused; ## Specific properties case "alphamap" s.doc = sprintf (doc_notimpl, "Transparency"); case "closerequestfcn" s.valid = valid_fcn; case "color" 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.valid = "N-by-3 matrix"; case "currentaxes" s.doc = "Handle to the graphics object of the current axes."; s.valid = valid_handle; case "currentcharacter" s.doc = doc_unused; case "currentobject" 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\ @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\ @end table"; s.valid = valid_2elvec; case "dockcontrols" s.doc = doc_unused; case "doublebuffer" case "filename" case "integerhandle" 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\ @table @code\n\ @item Character:\n\ The ASCII value of the key\n\ @item Key:\n\ lowercase value of the key\n\ @item Modifier:\n\ A cell array containing strings representing the modifiers pressed \ with the key.\n\ @end table"; s.valid = valid_fcn; case "menubar" case "mincolormap" 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.valid = valid_string; case "nextplot" case "numbertitle" 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.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."; case "papersize" s.doc = "Vector @qcode{[width height]} defining the size of the \ printing paper. 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. \ Setting __prop__ also changes @code{papersize} accordingly."; case "paperunits" s.doc = "The unit used to compute the @code{paperposition} \ property."; case "pointer" case "pointershapecdata" s.doc = doc_unused; case "pointershapehotspot" s.doc = doc_unused; case "position" s.valid = valid_4elvec; case "renderer" case "renderermode" case "resize" case "resizefcn" s.valid = valid_fcn; case "selectiontype" case "toolbar" case "units" s.doc = "The unit used to compute the @code{position} and \ @code{outerposition} properties."; case "windowbuttondownfcn" s.doc = "@xref{XREFfigurewindowbuttonupfcn, , \ windowbuttonupfcn property}."; s.valid = valid_fcn; case "windowbuttonmotionfcn" s.doc = "@xref{XREFfigurewindowbuttonupfcn, , \ 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."; s.valid = valid_fcn; case "windowkeypressfcn" s.valid = valid_fcn; case "windowkeyreleasefcn" s.valid = valid_fcn; case "windowscrollwheelfcn" s.valid = valid_fcn; case "windowstyle" case "wvisual" case "wvisualmode" 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}."; endswitch ## Axes properties elseif (strcmp (objname, "axes")) switch field ## Overridden shared properties case "clipping" s.doc = doc_unused; ## Specific properties case "activepositionproperty" case "alim" s.doc = sprintf (doc_notimpl, "Transparency"); case "alimmode" case "ambientlightcolor" s.doc = sprintf (doc_notimpl, "Light"); case "box" s.doc = "Control wether the axes has a surrounding box."; case "cameraposition" s.valid = valid_3elvec; case "camerapositionmode" case "cameratarget" s.valid = valid_3elvec; case "cameratargetmode" case "cameraupvector" s.valid = valid_3elvec; case "cameraupvectormode" case "cameraviewangle" s.valid = "scalar"; case "cameraviewanglemode" case "clim" 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.valid = valid_color; case "colororder" s.doc = "RGB values to be 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.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__."; 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.valid = valid_string; case "fontsize" s.doc = "Size of the font to be used for axes annotations. \ @xref{XREFaxesfontunits, , fontunits property}."; s.valid = "scalar"; case "fontunits" s.doc = "Unit used to interpret @code{fontsize} property."; case "fontweight" case "gridlinestyle" case "interpreter" case "layer" case "linestyleorder" case "linewidth" case "minorgridlinestyle" 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 \ 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 \ 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}."; 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 \ 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 \ 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}."; s.valid = valid_4elvec; case "projection" case "tickdir" case "tickdirmode" case "ticklength" case "tightinset" case "title" s.doc = "Graphics handle of the title text object."; s.valid = valid_handle; case "units" case "view" s.doc = "Specify the view point 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\"}"}); case "xdir" case "xgrid" s.doc = "Control wether major x grid lines are displayed."; case "xlabel" s.doc = "Graphics handle of the x label text object."; s.valid = valid_handle; case "xlim" s.doc = "Specify the limits for x-axis. __modemsg__. \ @xref{XREFxlim, , xlim function}."; s.valid = valid_2elvec; case "xlimmode" case "xminorgrid" s.doc = "Control wether minor x grid lines are displayed."; case "xminortick" case "xscale" case "xtick" s.doc = "Position of x tick marks. __modemsg__."; s.valid = "vector"; case "xticklabel" s.doc = "Labels of x tick marks. __modemsg__."; s.valid = valid_cellstring; case "xticklabelmode" case "xtickmode" case "yaxislocation" case "ycolor" s.doc = "Color of the y-axis. @xref{Colors, , colorspec}."; s.valid = packopt ({markdef(valid_color), ... "@qcode{\"none\"}"}); case "ydir" case "ygrid" s.doc = "Control wether major y grid lines are displayed."; case "ylabel" s.doc = "Graphics handle of the y label text object."; s.valid = valid_handle; case "ylim" s.doc = "Specify the limits for y-axis. __modemsg__. \ @xref{XREFylim, , ylim function}."; s.valid = valid_2elvec; case "ylimmode" case "yminorgrid" s.doc = "Control wether minor y grid lines are displayed."; case "yminortick" case "yscale" case "ytick" s.doc = "Position of y tick marks. __modemsg__."; s.valid = "vector"; case "yticklabel" s.doc = "Labels of y tick marks. __modemsg__."; s.valid = valid_cellstring; case "yticklabelmode" case "ytickmode" case "zcolor" s.doc = "Color of the z-axis. @xref{Colors, , colorspec}."; s.valid = packopt ({markdef(valid_color), ... "@qcode{\"none\"}"}); case "zdir" case "zgrid" s.doc = "Control wether major z grid lines are displayed."; case "zlabel" s.doc = "Graphics handle of the z label text object."; s.valid = valid_handle; case "zlim" s.doc = "Specify the limits for z-axis. __modemsg__. \ @xref{XREFzlim, , zlim function}."; s.valid = valid_2elvec; case "zlimmode" case "zminorgrid" s.doc = "Control wether minor z grid lines are displayed."; case "zminortick" case "zscale" case "ztick" s.doc = "Position of z tick marks. __modemsg__."; s.valid = "vector"; case "zticklabel" s.doc = "Labels of z tick marks. __modemsg__."; s.valid = valid_cellstring; case "zticklabelmode" case "ztickmode" endswitch ## Line properties elseif (strcmp (objname, "line")) 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.valid = valid_color; case "displayname" s.doc = "The text of the legend entry corresponding to this \ line."; s.valid = valid_cellstring; case "erasemode" s.doc = doc_unused; case "interpreter" case "linestyle" s.doc = "@xref{Line Styles}."; case "linewidth" s.doc = "Width in points of the line object."; case "marker" s.doc = "The shape of the marker to be used. @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}."; 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 \ can also be set to any color. @xref{Colors, , colorspec}."; case "markersize" s.doc = "Size of the markers in points."; s.valid = "scalar"; case "xdata" s.doc = "Vector of x data to be plotted."; s.valid = "vector"; case "xdatasource" 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.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.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 ## Overridden shared properties case "children" s.doc = doc_unused; ## Specific properties case "backgroundcolor" s.doc = sprintf (doc_notimpl, "Background area"); s.valid = valid_color; case "color" s.doc = "Color of the text. @xref{Colors, ,colorspec}. "; s.valid = valid_color; case "displayname" case "edgecolor" s.doc = sprintf (doc_notimpl, "Background area"); s.valid = valid_color; case "editing" case "erasemode" s.doc = doc_unused; case "extent" case "fontangle" s.doc = "Flag whether the font is italic or normal. \ @code{fontangle} is currently unused."; case "fontname" s.doc = "The font used for the text."; s.valid = valid_string; case "fontsize" s.doc = "The font size of the text."; s.valid = "scalar"; case "fontunits" s.doc = "The units used to interpret @code{fontsize} \ property."; case "fontweight" s.doc = "Flag whether the font is bold, etc."; case "horizontalalignment" case "interpreter" case "linestyle" s.doc = sprintf (doc_notimpl, "Background area"); case "linewidth" s.doc = sprintf (doc_notimpl, "Background area"); s.valid = "scalar"; case "margin" s.doc = sprintf (doc_notimpl, "Background area"); 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.valid = valid_4elvec; case "rotation" s.doc = "The angle of rotation for the displayed text, \ measured in degrees."; s.valid = "scalar"; case "string" s.doc = "The text object string content."; s.valid = valid_string; case "units" case "verticalalignment" endswitch ## Image properties elseif (strcmp (objname, "image")) switch field ## Overridden shared properties case "children" s.doc = doc_unused; ## Specific properties case "alphadata" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = valid_scalmat; case "alphadatamapping" s.doc = sprintf (doc_notimpl, "Transparency"); case "cdata" s.valid = "matrix"; case "cdatamapping" case "displayname" s.doc = "The text of 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.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.valid = valid_2elvec; endswitch ## Surface properties elseif (strcmp (objname, "surface")) switch field ## Overridden shared properties case "children" s.doc = doc_unused; ## Specific properties case "alphadata" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = valid_scalmat; case "alphadatamapping" s.doc = sprintf (doc_notimpl, "Transparency"); case "ambientstrength" s.doc = sprintf (doc_notimpl, "Light"); case "backfacelighting" s.doc = sprintf (doc_notimpl, "Light"); case "cdata" s.valid = "matrix"; case "cdatamapping" case "cdatasource" case "diffusestrength" s.doc = sprintf (doc_notimpl, "Light"); case "displayname" s.doc = "The text of the legend entry corresponding to this \ surface."; case "edgealpha" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = "scalar"; case "edgecolor" case "edgelighting" s.doc = sprintf (doc_notimpl, "Light"); case "erasemode" s.doc = doc_unused; case "facealpha" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = valid_scalmat; case "facecolor" case "facelighting" s.doc = sprintf (doc_notimpl, "Light"); case "interpreter" case "linestyle" s.doc = "@xref{Line Styles}."; case "linewidth" s.doc = "@xref{XREFlinelinewidth, , line linewidth \ property}."; case "marker" s.doc = "@xref{Marker Styles}."; case "markeredgecolor" s.doc = "@xref{XREFlinemarkeredgecolor, , line \ markeredgecolor property}."; case "markerfacecolor" s.doc = "@xref{XREFlinemarkerfacecolor, , line \ markerfacecolor property}."; case "markersize" s.doc = "@xref{XREFlinemarkersize, , line \ markersize property}."; s.valid = "scalar"; case "meshstyle" case "normalmode" case "specularcolorreflectance" s.doc = sprintf (doc_notimpl, "Light"); case "specularexponent" s.doc = sprintf (doc_notimpl, "Light"); case "specularstrength" s.doc = sprintf (doc_notimpl, "Light"); case "vertexnormals" case "xdata" s.valid = "matrix"; case "xdatasource" case "ydata" s.valid = "matrix"; case "ydatasource" case "zdata" s.valid = "matrix"; case "zdatasource" endswitch ## Patch properties elseif (strcmp (objname, "patch")) switch field ## Overridden shared properties case "children" s.doc = doc_unused; ## Specific properties case "alphadatamapping" s.doc = sprintf (doc_notimpl, "Transparency"); case "ambientstrength" s.doc = sprintf (doc_notimpl, "Light"); s.valid = "scalar"; case "backfacelighting" s.doc = sprintf (doc_notimpl, "Light"); 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."; s.valid = valid_scalmat; case "diffusestrength" s.doc = sprintf (doc_notimpl, "Light"); s.valid = "scalar"; case "displayname" s.doc = "The text of the legend entry corresponding to this \ patch."; case "edgealpha" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = valid_scalmat; case "edgecolor" case "edgelighting" s.doc = sprintf (doc_notimpl, "Light"); case "erasemode" s.doc = doc_unused; case "facealpha" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = valid_scalmat; case "facecolor" ## 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{\"flat\"}", ... "@qcode{\"none\"}", ... "@qcode{\"interp\"}"}); case "facelighting" s.doc = sprintf (doc_notimpl, "Light"); case "faces" case "xdata" s.valid = valid_vecmat; case "facevertexalphadata" s.doc = sprintf (doc_notimpl, "Transparency"); s.valid = valid_scalmat; case "facevertexcdata" case "interpreter" s.doc = doc_unused; case "linestyle" case "linewidth" case "marker" s.doc = "@xref{XREFlinemarker, , line marker property}."; case "markeredgecolor" s.doc = "@xref{XREFlinemarkeredgecolor, , line \ markeredgecolor property}."; case "markerfacecolor" s.doc = "@xref{XREFlinemarkerfacecolor, , line \ markerfacecolor property}."; case "markersize" s.doc = "@xref{XREFlinemarkersize, , line \ markersize property}."; s.valid = "scalar"; case "normalmode" case "specularcolorreflectance" s.doc = sprintf (doc_notimpl, "Light"); s.valid = "scalar"; case "specularexponent" s.doc = sprintf (doc_notimpl, "Light"); s.valid = "scalar"; case "specularstrength" s.doc = sprintf (doc_notimpl, "Light"); s.valid = "scalar"; case "vertexnormals" case "vertices" s.valid = valid_vecmat; case "xdata" s.valid = valid_vecmat; case "ydata" s.valid = valid_vecmat; case "zdata" s.valid = valid_vecmat; endswitch endif ## Replace keywords if (! isempty (s.doc) && ! strcmp (objname, "base")) s.doc = expand_doc (s.doc, field, objname); endif endfunction function strout = expand_doc (strin, field, objname) strout = strrep (strin, "__objname__", objname); strout = strrep (strout, "__prop__", ["@code{" field "}"]); modemsg = "Setting @code{%s} also forces the @code{%smode} \ property to be set to @qcode{\"manual\"}"; modemsg = sprintf (modemsg, field, field); strout = strrep (strout, "__modemsg__", modemsg); endfunction function s = getstructure (objname, base = []) hf = []; if (! strcmp (objname, "root")) ## Use an improbable figure 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. if (strcmp (objname, "base")) ## 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; elseif (strcmp (objname, "figure")) h = hf; else if (strcmp (objname, "image")) ## Disable GraphicsMagick warnings warning ("off"); endif eval (["h = " objname " ();"]); endif gprop = get (h); sprop = set (h); fields = fieldnames (gprop); nf = numel (fields); args = cell (2*nf, 1); for ii = 1:nf field = fields{ii}; ## Get hard coded documentation val = getdoc (objname, field, base); ## Extract the default values that are not hard coded in getdoc if (isempty (val.default) && val.printdefault) val.default = getdefault (h, objname, field); endif val.isreadonly = ! isfield (sprop, field); ## 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)) ## Add double quotes around string radio properties val.valid = cellfun (@(s) ["@qcode{\"" s "\"}"], val.valid, "uniformoutput", false); val.valid = strjoin (val.valid, ' | '); endif endif args{2*(ii-1)+1} = field; args{2*ii} = val; endfor ## Build struct and remove unused fields in base properties s = struct (args{:}); if (strcmp (objname, "base")) s = rmfield (s, {"displayname", "erasemode"}); endif if (isfigure (hf)) close (hf) endif endfunction function def = getdefault (h, objname, field) ## This function is meant to be run without initialization file so ## that the properties we get are the default. def = get (h, field); ## Don't print default values for graphics handles if (isscalar (def) && def != 0 && ishandle (def)) def = ""; else if (ischar (def)) def = ["@qcode{\"" def "\"}"]; else if ((isvector (def) && numel (def) < 5) || isempty (def)) ## Use disp to print the default value for short vectors and ## empty values str = disp (def); str(end) = []; # remove linefeed str = strtrim (str); # remove leading space ## Add [] around vector values if (ismatrix (def) && numel (def) > 1) str = ["[" str "]"]; ## Add ";" between columns vector values if (rows (def) != 1) str = strrep (str, "\n", "; "); endif endif ## Replace texinfo reserved characters def = strrep (str, "{", "@{"); def = strrep (def, "}", "@}"); def = strrep (def, "@", "@@"); def = ["@code{" def "}"]; else args = arrayfun (@(x) num2str (x), size (def), "uniformoutput", false); def = [strjoin(args, "-by-") " " class(def)]; endif endif endif endfunction function str = printdoc (objname, obj) ## Sort fields so that they appear in alphabetic order in the manual fields = sort (fieldnames (obj)); nf = numel (fields); ## 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")' str = sprintf ("%s@anchor{XREF%s%s}\n@cindex %s %s\n", str, objname, field, objname, field); ## Item str = sprintf ("%s@item @code{%s}", str, field); ## Mark item read-only if needed if (obj.(field).isreadonly) str = sprintf ("%s (read-only):", str); else str = sprintf ("%s:", str); endif ## Print valid and default values tmp = print_options (obj.(field).valid, obj.(field).default); if (! isempty (tmp)) str = sprintf ("%s %s\n", str, tmp); else str = sprintf ("%s\n", str); endif ## Print documentation str = sprintf ("%s%s\n", str, obj.(field).doc); endfor ## End of properties table str = sprintf ("%s\n@end table", str); endfunction function str = warn_autogen () str = "@c DO NOT EDIT! Generated automatically by genpropdoc.m.\n\ \n\ @c Copyright (C) 2014 Pantxo Diribarne\n\ @c\n\ @c This file is part of Octave.\n\ @c\n\ @c Octave is free software; you can redistribute it and/or modify it\n\ @c under the terms of the GNU General Public License as published by the\n\ @c Free Software Foundation; either version 3 of the License, or (at\n\ @c your option) any later version.\n\ @c\n\ @c Octave is distributed in the hope that it will be useful, but WITHOUT\n\ @c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or\n\ @c FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License\n\ @c for more details.\n\ @c\n\ @c You should have received a copy of the GNU General Public License\n\ @c along with Octave; see the file COPYING. If not, see\n\ @c <http://www.gnu.org/licenses/>."; endfunction function str = print_options (val, default) str = ""; if (! isempty (val)) tmp = strrep (val, default, ["@{" default "@}"]); if (length (tmp) == length (val) && ! isempty (default)) str = [tmp ", def. " default]; else str = tmp; endif elseif (! isempty (default)) str = ["def. " default]; endif endfunction