RE: [office-formula] Style for Function Descriptions

["Dennis E. Hamilton" <dennis.hamilton@acm.org>]

Using my original numbers, perhaps the following observations may be
helpful,

4. It is ordinary to define what the parameters (and results) are,
especially when they have some sort of particular significance (e.g.,
ordinal-represented calendar date, a rate of interest, or an angle expressed
in radians and in the interval -PI() < x <= PI() [and the use of PI() [given
a better definition, by the way], rather than p (mathematical constant pi)
is intentional here].
   It is also important because we are talking about computational
representations of parameters and results for functions to be realized by
computational methods (whether characterized mathematically or otherwise).
   It is not necessary to provide a reference work in any of the topics you
suggest, but sufficient definition so that one can ascertain what
specialized source, if any, is appropriate and which is being represented.
Providing references sources might be important in some cases, but I am
mainly concerned with sufficient definition that one could confirm that an
implementation delivered the requisite function, to some ascertainable
precision.

5. If default constraint-violation response is all that is required, that is
all that needs to be stated, provided of course that one can easily locate
what the default is.  The practice of stating this explicitly is a
demonstration of care and removes concern that omission is an oversight.  

6. See (5).  I am not asking for duplication but there are clearly error
cases that arise as a result of constraints or computational limitations.
When anything specific is expected, it should be called out.  If there is
nothing exceptional, it would be good to declare that in some simple way.
(The paragraph that isn't clear to you is intended to mean nothing more than
that.)

10. I have no objection to one computational function being defined in terms
of another one, when that is indeed what is meant by the use of the same
capitalized function-reference form.  I am concerned when that is not the
case and the use of an OpenFormula expression is not intended.  (In using
the PI() example in (4), I didn't have in mind any place where that is
appropriate, but can conceive of the possibility it might be appropriate in
some instance.  Cases where PI() > p might be troublesome unless some sort
of e (epsilon) allowance is made.)

 - Dennis

-----Original Message-----
From: Andreas J. Guelzow [mailto:aguelzow@pyrshep.ca] 
http://lists.oasis-open.org/archives/office-formula/200912/msg00163.html
Sent: Saturday, December 26, 2009 12:41
To: office-formula@lists.oasis-open.org
Subject: Re: [office-formula] Style for Function Descriptions

On Sat, 2009-12-26 at 12:12 -0800, Dennis E. Hamilton wrote:
http://lists.oasis-open.org/archives/office-formula/200912/msg00162.html
> 4. Move the summary of what the parameter values are used to represent up
> with the syntax, result type (and summary description) so that those
aspects
> are presented together.

As far as I am concerned, "what the parameter values are used to
represent" is unnecessary fluff. The standard needs to describe the
output expected given a certain input. It is up to the user to verufy
whether the formula is appropriate for their use. Otherwise the standard
has to become a reference work for Mathematics, Statistics, Accounting,
Actuarial Math, Engineering, etc.   
> 
> 5. With regard to hard constraints, indicate the kind of error a violation
> is.

This is already described elsewhere, and, imho, should not be duplicated
for every function.

> 
> 6. Say something explicit about errors that arise, errors that are
> propagated (not always a wonderful idea), and errors that are absorbed.

This is already done elsewhere. We only need to mention it for
exceptions. Again I don't think that duplication is a good idea.

> There are probably simple cases to be identified in a general place (as is
> done somewhat already) with reference to the applicable case, with any
> qualifications, from the individual function descriptions.

I don't know what this means.
> 

> 10. It is peculiar to have a mathematical formula that has
> spreadsheet-function names being used as if it is a mathematical function
> and we should avoid that.  It is one thing to observe that floor(-x) = -
> ceil(x), which is always true for non-complex x, but it might not be true
to
> say that FLOOR(-x) = - CEIL(x) because of Number representation edge cases
> (and I made that mistake on this list somewhere).  Similarly, while we can
> say with confidence that -1 < tanh(x) < 1, that might not apply for
> TANH(Number x) unless we are prepared to require that the computation be
> that tight, with computational rounding to 1 or -1 not permitted.  (If
> rounding to magnitude 1 is permitted for the delivered computational
result,
> there are consequences for ATANH(Number x) edge cases too.  It is rather
> unexpected for ATANH(TANH(x)) to ever fail for Number x not an error
> result.)

I think there are situations where we want to have spreadsheet functions
defined in terms of other spreadsheet functions.

Andreas


-- 
Andreas J. Guelzow <aguelzow@pyrshep.ca>


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php