*** Bug 115471 has been marked as a duplicate of this bug. ***

*** Bug 115452 has been marked as a duplicate of this bug. ***

*** Bug 115107 has been marked as a duplicate of this bug. ***

We need to unify function notation.
Currently we have a few ways of syntax representation:
SOMEFUNCTION(arg1,arg2)
SOMEFUNCTION(arg1, arg2)
SOMEFUNCTION (arg1,arg2)
SOMEFUNCTION (arg1, arg2)
I propose to use the first, both for the SYNTAX as well as the
EXAMPLES field. Another inconsistency is the use of spaces in the
SEEALSO field, where we have
@SEEALSO=fun1,fun2
as well as
@SEEALSO=fun1, fun2.

I could compile a patch against HEAD fixing this issues - we first
have to determine which format is preferred.

regs,
 Chris

For readability's sake I would opt for the option with spaces: 
SOMEFUNCTION (arg1, arg2)
Especially in the examples, the arguments quickly become unreadable if
everything is grouped toghether:
SOMEOTHERFUNCTION(5.1,2,4.63,3.2)

I'd rather not start making sweeping changes in the format just before freeze.

1) it will make the translators lives miserable
2) we're going to rework the format into something more manageable during 1.3.
   revamping the format twice seems pointless.

Are there any remaining issues in this bug ?

I have some string issues to be reported too, but it can be more
convenient to add to this report instead of creating one for my own:

----------------------------------------
#: plugins/fn-string/functions.c:102
"@FUNCTION=UNICHAR\n"
"@SYNTAX=UNICHAR(x)\n"
"@DESCRIPTION=UNICHAR returns the unicode character represented by the
number "
"@x.\n"
"\n"
"@EXAMPLES=\n"
"UNICHAR(65) equals A.\n"
"UNICHAR(8232) equals an carriage return error.\n"

-- What is "carriage return error"? Besides, 8232 = U+2028, which is
"LINE SEPERATOR".
If this is something wrong, I'd suggest changing it to, say:
"UNICHAR(960) equals the greek small letter pi.\n"

----------------------------------------
#: plugins/fn-complex/functions.c:1248
msgid ""
"@FUNCTION=IMARCCSCH\n"
"@SYNTAX=IMARCCSCH(inumber)\n"
"@DESCRIPTION=IMARCCSCH returns the complex hyperbolic arccosecant of
the "
"complex number z (@inumber), where\n"
"\n"
"\tarccsch(z) = arcsin(1/z).\n"

-- Should be arccsch(z) = arcsinh(1/z).

----------------------------------------
#: plugins/fn-complex/functions.c:1484
msgid "real,im[,suffix]"

-- Should be "real,im,suffix"

----------------------------------------
#: plugins/fn-date/functions.c:163
msgid ""
"@FUNCTION=DATE2UNIX\n"
"@SYNTAX=DATE2UNIX(serial)\n"
"@DESCRIPTION=DATE2UNIX converts a spreadsheet date and time serial
number "
"into a unix time.\n"
"\n"
"A unix time is the number of seconds since midnight January 1, 1970.\n"
"\n"
"@EXAMPLES=\n"
"\n"

-- We could have added an example here, such as:
"DATE2UNIX("01/01/2000") equals 946656000.\n"

----------------------------------------
#: plugins/fn-info/functions.c:1162
msgid ""
"@FUNCTION=EXPRESSION\n"
"@SYNTAX=EXPRESSION(cell)\n"
"@DESCRIPTION=EXPRESSION returns expression in @cell as a string, or
empty if "
"the cell is not an expression.\n"
"@EXAMPLES=\n"
"in A1 EXPRESSION(A2) equals 'EXPRESSION(A3)'.\n"
"in A2 EXPRESSION(A3) equals empty.\n"

-- The example is ambiguous because we know nothing about what is in
A3. The execution order of examples is important too. Suggestion:
"@EXAMPLES=\n"
"When A3 is an empty cell,\n"
"entering EXPRESSION(A3) in A2 equals empty.\n"
"Afterwards, entering EXPRESSION(A2) in A1 equals 'EXPRESSION(A3)'.\n"

----------------------------------------
#: plugins/fn-math/functions.c:1130
msgid ""
"@FUNCTION=POWER\n"
"@SYNTAX=POWER(x,y)\n"
"@DESCRIPTION=POWER returns the value of @x raised to the power @y.\n"
"\n"
"* This function is Excel compatible.\n"
"\n"
"@EXAMPLES=\n"

-- Execptional cases should be documented more clearly:
"POWER returns the value of @x raised to the power @y.\n"
"\n"
"* If both @x and @y equals to 0, POWER returns #NUM! error.\n"
"* If @x = 0 and @y < 0, POWER returns #DIV/0! error.\n"
"* If @x < 0 and @y is non-integer, POWER returns #NUM! error.\n"
"* This function is Excel compatible.\n"

----------------------------------------
#: plugins/fn-math/functions.c:1558
msgid ""
"@FUNCTION=TRUNC\n"
"@SYNTAX=TRUNC(number[,digits])\n"
"@DESCRIPTION=TRUNC function returns the value of @number truncated to
the "
"number of digits specified.\n"
"\n"
"* If @digits is omitted then @digits defaults to zero.\n"
"* This function is Excel compatible.\n"
" \n"
"@EXAMPLES=\n"

-- Same for POWER(), needs more documentation on exceptional cases.
           "TRUNC function returns the value of @number "
-          "truncated to the number of digits specified.\n\n"
+          "truncated to the number of digits specified.\n"
+          "\n"
           "* If @digits is omitted then @digits defaults to zero.\n"
+          "* If @digits is not an integer, it is truncated.\n"
+          "* If @digits is less than zero, @number is truncated "
+          "to the left of the decimal point.\n"
           "* This function is Excel compatible.\n "
           "\n"
           "@EXAMPLES=\n"
           "TRUNC(3.12) equals 3.\n"
           "TRUNC(4.15,1) equals 4.1.\n"
+          "TRUNC(-455.5,-1) equals -450.\n"

----------------------------------------
#: plugins/fn-math/functions.c:141
msgid ""
"@FUNCTION=GCD\n"
"@SYNTAX=GCD(number1,number2,...)\n"
"@DESCRIPTION=GCD returns the greatest common divisor of given numbers.\n"
"\n"
"* If any of the arguments is less than zero, GCD returns #NUM! error.\n"

-- It is "If any of the arguments is less than one".

----------------------------------------
#: plugins/fn-math/functions.c:193
msgid ""
"@FUNCTION=LCM\n"
"@SYNTAX=LCM(number1,number2,...)\n"
"@DESCRIPTION=LCM returns the least common multiple of integers.  The
least "
"common multiple is the smallest positive number that is a multiple of
all "
"integer arguments given.\n"
"\n"
"* If any of the arguments is less than one, LCM returns #NUM! error.\n"
"* This function is Excel compatible.\n"

-- Missing one condition:
"* If any of the arguments is non-integer, it is truncated.\n"
----------------------------------------

#: plugins/fn-math/functions.c:917
msgid ""
"@FUNCTION=BETA\n"
"@SYNTAX=BETA(a,b)\n"
"@DESCRIPTION=BETA function returns the value of the mathematic beta
function "
"extended to all real numbers except 0 and negative integers.\n"
"\n"
"* If @a or @b are 0 or negative integers, BETA returns #NUM! error.\n"
"\n"
"@EXAMPLES=\n"
"\n"

-- Should be:
"* If at least one of @a, @b or @a + @b are non-positive integers,
BETA returns #NUM! error.\n"

And examples can be given:
+          "BETA(2,3) equals 0.083333.\n"
+          "BETA(-0.5,0.5) equals #NUM!.\n"

----------------------------------------
#: plugins/fn-math/functions.c:944
msgid ""
"@FUNCTION=BETALN\n"
"@SYNTAX=BETALN(a,b)\n"
"@DESCRIPTION=BETALN function returns the natural logarithm of the
absolute "
"value of the beta function.\n"
"\n"
"* If @a or @b are non-positive integers, BETALN returns #NUM! error.\n"

-- Same as BETA() above. Should be:
"* If at least one of @a, @b or @a + @b are non-positive integers,
BETA returns #NUM! error.\n"

typo. In the comment JUST above, I mean BETALN instead of BETA.

I tried making a new bugreport, but it failed, so i'm appending my
string issues here.

I've also found some string errors in the decription of the functions.
(and one grammatical error) (this is using cvs version of 16-jul-2003

I'll summarize them below:

------------------------------
the arguments and the corresponding description of the arguments don't
match in
AMORDEGRC:

@FUNCTION=AMORDEGRC\n"
"@SYNTAX=AMORDEGRC(cost,purchase_date,first_period,salvage,period,rate[,"
"basis])\n"
"@DESCRIPTION=AMORDEGRC returns the depreciation for each accounting
period.\n"
"\n"
"@settlement is the settlement date of the security. @maturity is the "
"maturity date of the security. @basis is the type of day counting
system you "
"want to use:\n"

-------------------------------
Idem for AMORLINC
"@FUNCTION=AMORLINC\n"
"@SYNTAX=AMORLINC(cost,purchase_date,first_period,salvage,period,rate[,"
"basis])\n"
"@DESCRIPTION=AMORLINC returns the depreciation for each accounting
period.\n"
"\n"
"@settlement is the settlement date of the security. @maturity is the "
"maturity date of the security. @basis is the type of day counting
system you "
"want to use:\n"
-------------------------------
Idem for DURATION

@FUNCTION=DURATION\n"
"@SYNTAX=DURATION(settlement,maturity,coup,yield,freq[,basis])\n"
"@DESCRIPTION=DURATION calculates the duration of a security.\n"
"\n"
"@settlement is the settlement date of the security. @maturity is the "
"maturity date of the security. @issue is the issue date of the
security. "
"@rate is the interest rate set to the security. @pr is the price per
$100 "
"face value of the security. @basis is the type of day counting system
you "
"want to use:\n"
-------------------------------
Function SYD Example contains wrong argument:

@EXAMPLES=\n"
"For example say a company purchases a new computer for $5000 which
has a "
"salvage value of $200, and a useful life of three years. We would use
the "
"following to calculate the second year's depreciation using the SYD
method:\n"
"=SYD(5000, 200, 5, 2) which returns 1,280.00.\n"

should be:
"salvage value of $200, and a useful life of five years. We would use
the "
_____________________________________________^^^^_______________________
-------------------------------
YIELDMAT contains descriptoin of argument @frequency which is not an
argument in this function?

@FUNCTION=YIELDMAT\n"
"@SYNTAX=YIELDMAT(settlement,maturity,issue,rate,pr[,basis])\n"
"@DESCRIPTION=YIELDMAT calculates the annual yield of a security for
which "
"the interest is payed at maturity date.\n"
"\n"
"@settlement is the settlement date of the security. @maturity is the "
"maturity date of the security. @issue is the issue date of the
security. "
"@rate is the interest rate set to the security. @pr is the price per
$100 "
"face value of the security. @basis is the type of day counting system
you "
"want to use:\n"
"\n"
"  0  US 30/360\n"
"  1  actual days/actual days\n"
"  2  actual days/360\n"
"  3  actual days/365\n"
"  4  European 30/360\n"
"\n"
"* If @frequency is other than 1, 2, or 4, YIELDMAT returns #NUM!
error.\n"
"* If @basis is omitted, US 30/360 is applied.\n"
"* If @basis is not in between 0 and 4, #NUM! error is returned.\n

-------------------------------
RANDUNIFORM
the layout of the description is confusing: * If a <= x < b and 0
otherwise.

@DESCRIPTION=RANDUNIFORM returns a random variate from the uniform
(flat) "
"distribution from a to b. The distribution is,\n"
"\n"
"\tp(x) dx = {1 over (b-a)} dx.\n"
"\n"
"* If a <= x < b and 0 otherwise.\n"
"* If @a > @b RANDUNIFORM returns #NUM! error.\n"


better:
    p(x) dx = {1 over (b-a)} dx
    for a <= x < b

    p(x) dx = 0
    otherwise

or something similar
-------------------------------
EOMONTH

The arguments:  start_date and months in description should have a '@'
character in front:

* EOMONTH returns #NUM! if start_date or months are invalid
-------------------------------
Double negation in:

#: src/dialogs/dialog-solver.c:747
msgid ""
"Sensitivity nor limits report are not meaningful if the program has
integer "
"constraints. These reports will thus not be created

should be (remove 'not'):
"Sensitivity nor limits report are meaningful if the program has integer "
"constraints. These reports will thus not be created

or:
Sensitivity and limits report are not meaningful if the program has
integer 
"constraints. These reports will thus not be created
----------------------------------------------------

I'm not going to change the freeze message.

Nor the 'Insert Object' messages and friends.  That text shows up in
the undo menu.  I suppose the technically correct message would have been
'Inserted Object'.  There are a pile of different tenses in there.  We
can audit after 1.2 please open a new bug for this priority enhancement.

We'll handle the different basis types for 1.3 also when we can merge
all of those strings into 1 without making the translators explode.

I think thats all of them.

Jody, can you reopen it for now? There are indeed wrong description of
functions in the latter part of this report, that were bugs and not
enhancements. Besides, keeping this report open prevents everybody
forgetting it forever. Perhaps you have just checked the first few
parts of this report?

Well, this bug report has become useless. When I went through it (at
the same time as jody to have collided fixes afterwards) it seemed to
me taht all significant changes were made.

I think this report should be closed. If there are any remaining
issues, thay should be copied into a new bug so that they can be
addressed. As far as I am concerned this bug report is finished.

*** This bug has been marked as a duplicate of 117655 ***