Final call for reviews and comments on Xeta document specifications

[Low Zhen Lin]

http://svn.zynot.org/svn/zynot/projects/xeta/trunk/markup/dtd/
http://purl.oclc.org/zynot/xeta/current/dtd/

Either will get you there -- for a guaranteed address, use the PURL.

The Xeta document specifications specifies how to mark up and format
the following types of information:
* Package specification and metadata (XBuild)
* XBuild shared metadata (XBuild Project)
* XBuild repostory metadata (XBuild Tree)
* Package test-level, package trust-level, XBuild test-level, XBuild
trust-level (XBuild Ratings)
* Accountable votes (Signed Votes)
* File manifest, including checksums and signatures
* Changes
* Software licenses

We would like to finalise the markup specification as soon as
possible, your comments are appreciated. The dependency specification
specification is still a draft, and will be included in a later
dependency behaviour specification.

- -- Zhen Lin

[Daniel Albuschat]

Post by Low Zhen Lin
http://svn.zynot.org/svn/zynot/projects/xeta/trunk/markup/dtd/

--8<------------

Post by Low Zhen Lin
We would like to finalise the markup specification as soon as
possible, your comments are appreciated. The dependency specification
specification is still a draft, and will be included in a later
dependency behaviour specification.

I'll look into this by friday or saturday, since I'm a bit busy at the moment.
Please give me some time till then...

cu,
Daniel

--
eat(this); // delicious suicide

[Daniel Albuschat]

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.