[Enigma-devel] Comments on the level xml schema

[Tacvek]

While reading over the XML schema for XML levels, I noticed the following:

[These first comments on one the schema itself. Comments about the level 
format, and the implications for the schema can be found below.]

You define "xml:lang" as "en" on the <xs:schema>. This is good, and is a 
practice reccomended by the Schema documentaion in the
case that all <xs:documentation> tags are in the same language. When 
<xs:documentation> is available in multiple languages
then it is reccomended to drop that attribute from <xs:schema>.

It may be desireable to include optional attributes in the basic form
<xs:attribute ref="xml:space" default="preserve"/>
Changing "preserve" to whatever would fit that element.
On the other hand that syntax would allow a level to change
the "xml:space" attribute. If that is not desireable then
"fixed" should be used rather than default. Of course
there is no need whatsoever to add that tag, but it is reasonable.

Documentation is lightly scarce. In at least a few cases the meaning of a 
tag or attribute is not clear
from its name alone and could benefit from documentaion. For example, while 
I was able to
guess the meaning of the "open" attribute of the "licence" tag, the word 
"open" is sufficently
ambigious that documention would be a good idea.

There should probably be an "upgrade" type rather than two virtually 
identical tags.
If the two "extentions" tags represent the same basic thing, they should 
also probably be two
instaces of a seperately defined base type.

It would be nice to actually define the contents of the "elements" element, 
although this is not a priority as no
levels are using that yet.

[Comments on the format itself (at least as defined by the schema)]

"Titel" is German. As all the other tag/attribute names are in English 
(AFAICT), perhaps "title" should be used.

It is not clear to me what the "score" attribute of the "version" tag 
reprensents. This would be annother
good attribute to add documentation to the schema for.

The "author" tag is required although it must have no content, and all of 
its attributes are optional.
While entirely reasonable, especially because the default attribute for 
author name would
not be visable if there was no author tag, it does seem a little awkward. It 
is probaby not a big deal.

The "externaldata" tag represents a sufficently complex concept that it 
desrves documentation.
Based on the anyattribute element, I assume it is currently defined for 
compatibility with a future feature,
so an annotation explaining that is certainly reasonable.

The same goes for the "extentions" tag.

The modes attributes really could use documentation. For example "easy". 
While I
know what that means, a person might assume it meant that the level was 
easy, rather than
supporting easy mode. The "single" and "network" attributes could use some 
clarification.
I assume they are not mutually exclusive, but at least one of them must be 
true.
And I honstly have no clue what the "control" attribute represents.

The "update" and "upgrade" elements could use documentation, as i'm not 
really sure what they represent.

Why is the "easy" attribute of the "Score" element required?
It seems to me that levels without an easy mode should be allowed to omit 
it.

Rather than use an attribute in the Enigma namespace, it is recomended that 
"xml:lang" be used.
See: http://www.w3.org/International/questions/qa-when-xmllang
The appropriate tag is:
  <xs:attribute ref="xml:lang" use="required"/>
The level schema would require an import statement so that a parser could 
find the schema fragment that
defines xml:lang. The statement required is:
 <import namespace="http://www.w3.org/XML/1998/namespace";
              schemaLocation="http://www.w3.org/2001/xml.xsd"/>



[Comment on the current xml level examples]

It seems that it may be wise to use the default namespace feature in the 
level files to avoid excess prefixes.



Tacvek

P.S. You did receive my makefile fragment for generating lua-*.* from 
*-lua.pkg right?