Open Malaysia

XML was designed to be humanly readable, in that if a developer had to look at an XML document, the document in itself would be self descriptive and easily understandable without much need to refer to the specification. Human readability is also a measure of good interoperability as the easier to understand a document, the easier it is to write translators for it. A poorly defined XML specification is a specification which would define tags which are non-descriptive, confusing, have inconsistent naming conventions and this contradicts the spirit and purpose of XML.

The specific goals of XML which MSOOXML contradicts are:

6. XML documents should be human-legible and reasonably clear.

10. Terseness in XML markup is of minimal importance.

An example of where this is a problem with EOOXML is the treatment of XML Element and Attribute names. In the element “5.1.10.45 outerShdw (Outer Shadow Effect)” (page 4413) in the VML section, the naming convention is devoid of vowels in the second word (e.g. where Shadow becomes Shdw).

This is a common programming naming convention where the programmer trades off readability for the economical use of keystrokes. However this naming convention should not apply on the XML level, as it will cause confusion and hinder future understanding of a document.

Here is the EOOXML specification itself displaying the many Attributes of this Element 'outerShdw':

Take for example, the Child Elements and Attributes associated:

scrgbClr,  algn,  blurRad, dir,  dist, rotWithShape.

We need to query why these Attributes need to be so cryptic within the specification? As a recommendation, it would help the readability, clarity and consistency if these Attributes were renamed as such:

ScreenRGBColor, ShadowAlignment, BlurRadius, Direction, Distance, RotateWithShape

The 3 bytes saved in defining 'blurRad' versus 'BlurRadius' is not justifiable for the trade off for readability. It is even more so unnecessary with the 1 byte savings from 'align' to 'algn'.

Additionally, why is there a contradictory Element naming convention and Attribute naming conventions? The Element 'outerShdw' has its second word de-vowelled while Attributes like 'blurRad' and 'rotWithShape' do not exhibit de-voweling but instead a truncation of either first or seconds words. This selection seems arbitrary and inconsistent.

In addition, the naming convention itself is not consistent throughout the EOOXML specification.

In WordprocessingML, the attributes do not have the vowels removed. For example, the Element  “2.15.1.78 settings(Document Settings)” (page 2020) has a whole list of Child Elements have different naming conventions from the VML section.

The ones of interests are:

ActiveWritingStyle, attachedSchema, documentType, docVars, endnotePr, hdrShapeDefaults

'endnotePr' is similar to the VML convention except that Pr denotes 'Preference' when actually convention should dictate the name to be 'endnotePrfrnce'.

Note that even within the Child Elements of 'settings', there are inconsistencies. 'documentType' which is verbose and easy to read is contrasted with its sibling 'docVars' where the words 'document' and 'Variables' are both truncated. These two Child Elements should have their naming conventions harmonized to prevent significant confusion.

'hdrShapeDefaults' is another example of vowel removal, except that it is from the first word, which is another contradiction in naming conventions.

Naming conventions in source code should be as descriptive as possible, and should avoid unnecessary abbreviations. Taking from Microsoft's own Best Practices Manual “Code Complete” by Steve McConnell, which has pertinent questions regarding naming decisions:

• Does the code avoid abbreviations that save only one character?

• Are all words abbreviated consistently?

• Are the names pronounceable?

• Are short names documented in translation tables?  ... and more.

The argument to save bytes in modern computers is moot nowadays as RAM memory is abundant  in addition, the file will efficiently compress  repetitive elements. Therefore there should be no justifiable reason for the readability trade off as of yesteryear.

This issue betrays the source of the specification in that it is derived directly from a single implementation by Microsoft. This is why we can see the inconsistent and programmer centric  naming conventions which really should not be in a modern and progressive and descriptive international standard. The naming conventions used in EOOXML contradict Microsoft's internal Best Practices.

Readability is an issue in ISO standards as the audience is in essence international, where English would not be the native language. Abbreviating or obscuring the meanings of certain words which English speakers would take for granted, would be hard for a non English speaking programmer of a different background and culture to deduce and translate. This additional barrier is unnecessary and should be resolved if this specification is meant for the international audience.

The inconsistent and contradictory naming conventions within the different sections (WordprocessorML, SpreadsheetML, VML) and even within Attributes, Parent and Child Elements will cause considerable confusion, frustration and impede technical usage of this draft specification.

Until there is a consistent naming convention of the XML Elements and Attributes throughout the EOOXML specification, this specification remains a reference document at best and is far from a usable international standard.

The effect of this is that it contradicts the spirit of XML and SGML (ISO 8879) which is to promote readable structured document interchange.

yk