On 2012-01-16 11:37-0000 Andrew Ross wrote: > Alan, > > Many thanks for this! I've been slightly worried about this for some time > so it's nice that you've found a neater solution. > > Your documentation changes missed out a tag though which caused octave > documentation builds to fail. I've fixed this, but can you please > check that I've done what you intended.
I have made a further change (revision 12133) which validates and which also better represents what I want. This whole area of documenting redacted functional forms for languages that handle output arguments by moving them from the argument list to the left side of an assignment statement needs lots more work. For example: software@raven> grep ddata examples/*/*21* |grep "=" examples/lua/x21.lua: zg = pl.griddata(x, y, z, xg, yg, alg, opt[alg]) examples/ocaml/x21.ml: let zg = plgriddata x y z xg yg named_alg opt.(alg - 1) in examples/octave/p21.m: zg = griddata(x, y, z, xg, yg, i, opt(i)); examples/octave/x21c.m: zg = plgriddata(x, y, z, xg, yg, alg, opt(alg)); examples/perl/x21.pl: $zg = plgriddata ($x, $y, $z, $xg, $yg, $alg, $opt [$alg - 1]); examples/python/xw21.py: zg = plgriddata(x, y, z, xg, yg, alg, opt[alg-1]) shows that lua, ocaml, octave, perl, and python all use this method of dealing with output arguments with some small variations in syntax. I think we need a way to summarize this assignment-statement style (say by documenting the Python syntax but mentioning the others are similar) so we don't have to repeat this information individually for the 5 languages that use it. Furthermore, a quick review of bindings/swig-support/plplotcapi.i shows many OUTPUT variables and some OUTPUT arrays that need assignment-statement style documentation in the redacted forms for the above languages. In sum, we need some thought and experiment about how we actually want to handle the redacted case for languages that use an assignment-statement style. Once that decision is made, I am sure the form and maybe even the tags I used for the redacted case of plgriddata and python will need further changes. Also, once the big decisions are made for how to handle the assignment-statement style, then there is a fairly large but completely straightforward editing job on api.xml in the offing to implement those decisions. Alan __________________________ Alan W. Irwin Astronomical research affiliation with Department of Physics and Astronomy, University of Victoria (astrowww.phys.uvic.ca). Programming affiliations with the FreeEOS equation-of-state implementation for stellar interiors (freeeos.sf.net); the Time Ephemerides project (timeephem.sf.net); PLplot scientific plotting software package (plplot.sf.net); the libLASi project (unifont.org/lasi); the Loads of Linux Links project (loll.sf.net); and the Linux Brochure Project (lbproject.sf.net). __________________________ Linux-powered Science __________________________ ------------------------------------------------------------------------------ RSA(R) Conference 2012 Mar 27 - Feb 2 Save $400 by Jan. 27 Register now! http://p.sf.net/sfu/rsa-sfdev2dev2 _______________________________________________ Plplot-devel mailing list Plplot-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/plplot-devel
