Re: Final call for reviews and comments on Xeta document specifications

Hello Zhen Lin,

  Well I found some time to answer your mail... I hope my boss isn't too angry
about doing (at least beginning) it at my workplace :D

First of all, I think you can barely call DTDs a real `specification' [1]. 
It's more grammar than an explanation. The few comments you put in the DTD 
documents don't help non-knowing developers (including me and devs joining
us in the future) to understand the overall system.

What we need is
   - A descriptive _Text_, which explains everything _in detail_ (after
     all, that's what a specification is about).
   - Perhaps a simple figure that shows the cohension between
     the different nodes, and which nodes may be root nodes, etc.
   - The DTDs are only for veryfication that a xml-file is compatible
     to the spec.

Well, here are some comments on the DTD:

xbuild.dtd, line 9
| type (group | standard | config | abstract) 'standard'> <!-- abstract cannot be used in any way other than inheritance 
|                                                              group means that the xbuild equals its dependencies, i.e.
|                                                              when you unmerge a group, you unmerge its dependencies (one
|                                                              level only). -->

This is by far not clear to me -- what's the type good for?
What does it have to do with inheritance?
What does 'config' and 'standard' mean?

xbuild.dtd, line 26
| %commonDTD;
| %xbcommonDTD;
| %maintainersDTD;

What do these statements do?
Sorry, I'm not that familiar with DTD and couldn't find information
on the net.

xbuild.dtd, line 30
| <!ELEMENT subpkg EMPTY>
| <!ATTLIST subpkg
|   uuid ID #REQUIRED
|   name CDATA #REQUIRED> <!-- ASCII only, must be unique within the XBuild, but not between -->

What exactly is a sub-package? And why is there no explanation?
I think I already asked this question on irc, but
   a) It's still not very clear to me
   b) It's sure not clear to others who read the dtd.

xbuild.dtd, line 51
| <!ELEMENT slot (dict)> <!-- Take care! Runtime variable substitution is possible.
|                             Syntax defined in dependency spec. -->

Oh I'm _sure_ there's a discussion about slots somewhere, but 
that's a general zynot problem -- information is spread through too
many places...
Atm I can't imagine how they work, what problems they produce, what they
solve and so on. Can you give me a link to a description and, if
possible, include a brief summary about slots into the dtd? (Or the link)

xbuild.dtd, line 66
| <!-- Use only one uri, or one base64, or all text, but not any other combination -->
| <!-- syntax rules for each language still apply, but XML-escape '&', '<' and '>' -->
| 
| <!ELEMENT preamblecode (uri|base64|#PCDATA)*>
| <!ELEMENT code (uri|base64|#PCDATA)*>

--verbose,
please.

Hm ok, now I'm tired of reading DTDs, since they don't explain anything.
I can't say whether the DTD is ok for me, if the semantic rules and ideas aren't 
explained anywhere.

So I think that someone should sit down and write a nice specification.
And since Zhen Lin seems to be the only one who actually knows what the
DTDs mean, I guess I know who'll be that. :)

Honestly, the DTD is not enough to understand such a complex structure.

In addition to this, an updated (and complete) xmonolith.xml example file 
would be nice. At least to me, it's far easier to read.

regards, 
  Daniel Albuschat

[1] Where specification is meant as a `description' and definition of how
    something works.