Re: [office-formula] Formula Terminology

[Michael Brauer - Sun Germany - ham02 - Hamburg <Michael.Brauer@Sun.COM>]

Hi,

it seems we reached consensus on these items:

1. Constrains should not talk about errors, but just state the permitted 
values. That functions return an error if non-permitted values are used 
is said already in section 5.2, which should be adapted as follows:

"If a constraint is not met, the function/operator
*shall* return an error unless otherwise noted"

2. If the semantic description of function lists parameter values that 
result in an error, this may be moved into a constrain. However, not all 
statement that are made in the semantic description can be moved into 
constrains.


There was further some discussions regarding the use of "should". 
Regarding constrains for parameters, my recommendation is to use neither 
"should" nor "shall", but to just list the allowed values. For instance:

RATE()

Constraints: Rate>0, AnnualYield>0, Redemption>0, Frequency = 1, 2 or 4.

Why? The constrains for RATE() right now are:

Rate, AnnualYield, and Redemption should be greater than 0;
Frequency = 1, 2 or 4.

If we replace the "should" with "shall", then one may read this as that 
using a value outside the allowed range results in a non-conforming 
expression. But that's not what is intended to say. What is intended to 
say is that values outside the range result in errors at evaluation 
time. And that is already said in 5.2.

Best regards

Michael



On 01/13/10 23:29, robert_weir@us.ibm.com wrote:
> I'm noticing a lot of terminological issues in the financial functions, 
> especially the same concepts being referred to by multiple terms.  We 
> should strive to use different terms only when we want to refer to 
> different things.  A standard is not an exercise in creative writing. 
> Synonyms are not our friend.
> 
> I've started a Wiki page to track the issues as I find them.  Not much 
> there yet, but it will grow. 
> 
> http://wiki.oasis-open.org/office/Formula_Terminology
> 
> 
> I'm also wonder about the redundancy in the function summary and the 
> semantics.  In many cases the semantics section starts with a sentence 
> that is a verbatim repetition of  the function summary, often verbatim. 
> But sometimes it isn't.  I think we want to avoid redundancy here.  Maybe 
> we don't need the summary at all?
> 
> Constraints -- there also vary in the way they are used.  What is the 
> intent here?  For example, for PRICE():
> 
> Constraints: Rate, AnnualYield, and Redemption should be greater than 0; 
> Frequency = 1, 2 or 4.
> 
> 1) Why is this a "should"?
> 2) What happens if the constraints are violated?
> 
> Compare to RATE():
> 
>  If Nper is 0 or less than 0, the result is an error.
> 
> Do we really mean to say that constraint violations are errors in some 
> functions, but not in others?
> 
> Also, could we eliminate 80% of the constraints by simply defining 
> PositiveNumber and NonNegativeNumber pseudo-types?  It will be far easier 
> to express these kinds of constraints as datatype constraints than trying 
> to repeat these trivial constraints in the body of the text.
> 
> Regards,
> 
> -Rob
> 
> 
> ---------------------------------------------------------------------
> 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 
> 


-- 
Michael Brauer, Technical Architect Software Engineering
StarOffice/OpenOffice.org
Sun Microsystems GmbH             Nagelsweg 55
D-20097 Hamburg, Germany          michael.brauer@sun.com
http://sun.com/staroffice         +49 40 23646 500
http://blogs.sun.com/GullFOSS

Sitz der Gesellschaft: Sun Microsystems GmbH, Sonnenallee 1,
	   D-85551 Kirchheim-Heimstetten
Amtsgericht Muenchen: HRB 161028
Geschaeftsfuehrer: Thomas Schroeder, Wolfgang Engels, Wolf Frenkel
Vorsitzender des Aufsichtsrates: Martin Haering