OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

office message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: Re: [office] Please review syntax of formula work


I took a look at chapter 5 of the recent draft. My feedback is below.

Please not that I have wrote down everything I noticed while reading the 
chapter, and the questions I have added below are in most cases not really 
questions to the TC/SC, but shall indicate that something was not clear to 
me. Please note further that I'm not a spreadsheet/formula expert. So some 
questions actually may be caused by that fact, and may not be justified.

Please note further that although the list below seems to be long, I in 
general did like what I read.

Best regards



- There are multiple instances of "  " (two blank characters). One should be 

- References to external work should make us of the bibliography (see for 
instance reference to http://www.w3.org/TR/2004/REC-xml11-20040204/#sec-notation.
in the introduction to chapter 5.

- The OpenDocument specification currently refers to XML 1.0 (Third edition). 
Is there are reason why OpenFormula refers to XML 1.1?

- The OpenDocument specification uses a fixed font for everything that
may appear literally in a document and for inline examples. Maybe the formula 
specification should do the same. I think this may in particular be useful 
for the symbols of the BNF grammar (a few examples are below).

- The draft contains some explanations that help to understand why
certain decisions have been made (and that do not have a background), but 
that are not required to implement the specification. An example is in 
Section 5.7, the paragraph starting with

"This naming scheme enables different applications to innovate without
interfering with each other or with standard functions. ...".

My suggestion would be to remove these kind information from the normative 
specification document, but to have an annotated non-normative version that 
contains this information.

- Is it an option to move the test cases into a separate chapter? I think 
this may be advantageous for to reasons. First, I believe most readers of the 
specification are not interested in the test cases, but in a compact 
representation of the topic. Second, Implementors probably want to create 
test suites that cover all test cases, and therefore benefit from having them 
in one place, too.

Chapter 5

"When this occurs, various characters (such as "<", ">", '"', and "&") must 
be escaped, as described in the XML specification. In particular, the 
less-than symbol "<" is represented as &lt;, the double-quote symbol is 
represented as &quot;, and the ampersand symbol is represented as &amp;."


"When this occurs, various characters (such as "<", ">", '"', and "&") must 
be escaped, as described in section 2.4 of XML specification ([XML1.0]). In 
particular, the less-than symbol "<" must be represented as &lt; (or as a 
numeric character reference), the double-quote symbol as &quot;, and the 
ampersand symbol as &amp;.".

Section 5.1

"The optional namespace tells ..."


"An optional namespace prefix tells ..."

In general, I think most occurrences of "Namespace" in this section actually 
should be "namespace prefix".

Did the SC consider to remove namespace prefix from the grammar, and to 
describe it instead in a/the section that describes how formulas are embedded 
into OpenDocument documents?

"When used in OpenDocument attributes table:formula and text:formula, 
applications should not include this namespace, as it is unnecessary. ..."

I think this conflicts with the current OpenDocument specification, which 
says that a namespace prefix should be used. My suggestion would be that we 
state in the ODF 1.2 spec that a formula that has no prefix is an OpenFormula 
formula, and to state the same in the OpenFormula specification in a 
non-normative way. I'm not sure if we can do anything for ODF 1.0/1.1.

In general, I think the normative description how formulas are used within 
OpenDocument should be in the OpenDocument specification itself.

"Namespace_in_XML ::= http://www.w3.org/TR/REC-xml-names";

Does an URI in the BNF used here has a special meaning? If not, what about

"Namespace_in_XML ::= Prefix /* A prefix as declared in section 4 of 
[xml-names] */

I further would rename "Namespace_in_XML" into "Namespace_prefix"

Section 5.2

"simple" -> "simply"

"The primary component of a formula is an expression"


"The primary component of a formula is an Expression"

This makes clear you are not talking about expressions in general, but about 
the BNF production Expression. You may also use a fixed font in this case to 
make it look like the BNF.

"SingleQuoted ::= "

Why does "SingleQuoted" appear here? It's not used in this section.

"There is no special syntax for the logical constants for truth and falsity, 
since this is unnecessary;  simply use the ..."

I was first confuses to read this in that section, because "constants" have 
not been introduced before, but noticed later that "Number" and "String" are 
of course constants. So my suggestion would be rephrase this similar to

"While the formula syntax defines literal numbers and strings, it does not 
define literal string constants. Instead, the standard functions TRUE() and 
FALSE() [add a reference here] can be used."

Section 5.3

Is there a better name for "WrittenNumber" and the the term "written" in the 

Is there a formal reference to "C" or en-US locale. If not, I suggest
to remove the reference to locales.

Section 5.4

"Note that when a formula is stored as an XML attribute (the usual case), XML 
quoting rules apply: thus double-quote characters are recorded in the XML 
such as &quot;, and carriage return characters in the String are recorded as 
&#x0D;.A constant string as defined by this syntax, shall be considered to be 
type Text."


"Note that when a formula is stored as an XML attribute, XML escaping rules 
apply: thus double-quote characters must be escaped as &quot;, and carriage 
return characters in string constants as &#x0D;. A constant string as defined 
by this syntax, shall be considered to be type Text."

(It's not essential to change that, but I noticed that the introduction uses 
the term "escape", and this section the term "quote". Please note the missing 
space before the last sentence).

Section 5.5

"There two predefined" -> "There are two predefined"

"written as &amp;" -> "must be escaped using &amp;"

Sometimes the operator symbols (+, -, etc) are mentioned in the
description and sometimes this is not the case.

"Also note that while prefix "+" and "-" are right-associative, because
"+" is a no-operation, applications which implement at most these
operators, using only the semantics defined by this specification, may
implement them as left-associative since the results will be identical."

I have to admit that I don't understand that sentence.

"Implementations' user interfaces may display these operators differently or 
with a different precedence, but when exchanging formulas they shall use the 
precedence rules here."


"Implementations' user interfaces may display these operators differently or 
with a different precedence, but conforming applications must store formulas 
using the operator names and precedences defined in this specification."

In general, I would not use the term "exchange", because this sounds like 
OpenFormula being only an exchange format, what it clearly is not.

Section 5.6

"Functions are called by giving their named" -> "Functions are called by 
giving their name"

"LetterXML ::= ", "DigitXML ::= ", "CombiningCharXML ::=":  See my comment on 
URL's above.

"User-defined function names may use an arbitrary identifier,"

Does that mean that user-defined function names have to follow the production 
"Identifier"? Or does it mean that they can really use an arbitrary identifier?
I assume the first is the case. To make this clearer, I suggest to either 
format BNF grammar names (for instance by using a fixed font), or to add 
numbers to the productions and to reference them. The first option probably 
is much easier to implement, and also easier to maintain.

"Applications may (and often do) display a different function name in
their user interface than ..."


"Implementations' user interfaces may translate function names,
may omit application prefixes, or may replace the function names defined in 
this specification with arbitrary other function names, but conforming 
applications shall not use these functions names when storing formulas."

I further suggest to define what the application prefixes are, or to
reference section 5.7 and to use the terminology from that section.

Section 5.7

Is there a definition somewhere what the "standard" names are?

"Applications that do not support a function should compute its result as 
some Error value other than NA() when calculating its result."


"Applications that do not support a function should compute its result as 
some Error value other than NA()."

Section 5.8

"in the storage format": Are there different formats? If not, remove this.

"Where possible, applications should use references with embedded ":"
separators, instead of the general-purpose ":" operator, when saving
files, and where there is a choice of cells to join, and application
should choose the leftmost pair. "

This sentence becomes only clear then reading the next one. Reference to
definitions of the two ":" may help.

Are the explanations regarding URIs and relative IRIs/URIs required, or would 
it be sufficient to state that the could be absolute or relative IRIs?

Section 5.9

"Automatic lookup of labels can be enabled or disabled in the document 

Are these the application specific setting defined in OpenDocument, or 
something else? A reference may be helpful here.

Section 5.10

"Applications supporting named expressions must support named expressions 
that are global to all the sheets in a (spreadsheet) document in the current 
document (this is a named expression without a Source, QuotedSheetName, or 

- must is not in our control language any longer.

Would it be sufficient to say:

"Applications supporting named expressions shall support named expressions 
that are global to all sheets in the current (spreadsheet) document"

Is there a definition of "portable documents"?

Would it be possible to distribute the descriptions of the various named 
expression types and the grammar to the subsection?

Section 5.11

"The inline error value NA shall be represented as "#N/A" when represented as 
an inline error, and this is portable across implementations."

My understanding is that "#N/A" is the only portable error value, so my 
suggestion is to write:

"The only portable error values is "#N/A", which represents the NA inline 
error value."

The sentence

"Portable documents should not use inline error values other than #N/A, as 
error values are not necessarily portable between applications."

may be omitted then.

Section 5.12

"Applications that support inline arrays must accept"


"Applications that support inline arrays shall accept"

Section 5.13

"Whitespace (space, tab, newline, and carriage return) is ignored in the 
default formulas syntax, except inside the contents of string constants and 
text surrounded by single quotes"

Is there another than the default formula language? Suggestion

"Whitespace (space, tab, newline, and carriage return) shall be ignored, 
except it occurs inside the contents of string constants and text surrounded 
by single quotes"

Would it be an option to extend the grammar with whitespace characters, as it 
is the case of XML 1.0?

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]