[Enigma-devel] Re: Comments on the level xml schema

[Ronald Lamprecht]

Hi,

Tacvek wrote:
> 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>.

There will be no <xs:documentation> in multiple languages. I try to make 
very limited use of <xs:documentation> as it makes schemas quite 
unreadable.

You will find only technical infos in my <xs:documentation>. The "user" 
documentation you will find in the Enigma reference manual.  This 
documentation is very detailed on all semantical aspects. I keep the 
reference manual up to date with the schema. Note that not all features 
may yet be supported by the trunk version - read the commit messages 
about progress.

> 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.

I hope the level authors can live with the current whitespace default 
handling. I would like to keep the schema as simple as possible - for 
readability and maintance purposes.

> 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.

Read the reference manual.

> 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.

Read the reference manual.

> 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.

Due to a lack of time I just reserved the element and ensured that 
future levels can be read with current Enigma versions. The definition 
will follow ASAP.

> [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.

A typo - thanks, no one did spot this one yet!

> 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.

Read the reference manual.

> 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.

Read the reference manual.
I just want the few anonymous authors to be aware of their status and 
that we respect their rights.

> 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.

Read the reference manual.

> 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.

Read the reference manual.
Again I want to remember the author to supply an easy mode - technically 
an optional attribute with default value would be equivalent.

> 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"/>

I started with xml:lang, but did run into serious technical trouble. As 
far as I remember it was related to Xalan with the stylesheets that 
extract the translations and Xerces C++, too. Instead of spending my 
time to fix these problems I advanced with Enigma.

BTW I do want to keep Enigma capable of running standalone. Thus I do 
not want to import a schema from the internet and extending the resolver 
to take a local copy seems not to be worthwhile the benefits.

> [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.

As I want to separate Enigma's schema elements from those private once 
added by a level editor we have to live with the prefixes.

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

Your makefile rules may need configure.ac modifications, as with a fresh 
checkout from the repository the modification dates of *.cc and *.pkg 
are undetermined, but we cannot rebuild *.cc from *.pkg until we have 
tolua++. And tolua++ does not exists on process of configure.ac. That 
was the reason I first asked for a makefile target and not rules (and I 
guess the reason why Daniel did comment out the old rules). Just need 
some time to find a proper solution.

Thanks for the feedback

Ronald