[cduce-devel] preliminary XML Schema documentation

Giuseppe Castagna Giuseppe.Castagna at ens.fr
Fri Nov 21 00:08:05 CET 2003

On Thu, 2003-11-20 at 23:43, Stefano Zacchiroli wrote:
> On Thu, Nov 20, 2003 at 02:53:42PM +0100, Giuseppe Castagna wrote:
> > Excellent work. I just corrected some syntax and typos. Few suggestions:
> > - you should add a link to show mails.xsd definition.
> No, is not needed. The only time I reference to it is to show how to use
> the "schema" keyword. Next I use "Mails # mailType", but to understand
> the syntax you have non need to know the schema. Idem for the #env
> directive, you just see the "Mails" name in the list of imported schemas
> ...

When you explain things it is better to be rendundant. The fact that it
is not strictly necessary is not a good criteria. However too many
detail may blur the presentation, this is why I suggested to add it as a
link (e.g. ... which charges the schema <a href=...>mails.xsd</a>) and
not in the text.

> > - you should recall this link when you use for the first time
> >   envelopeType (otherwise you cannot understand the example)
> Ok, here you're right, I reference some types which aren't described. I
> will add the link.
> > - add also to mails.xsd new element so that the examples for attributes
> >   and elements declaration do not need New schemas Person and Calendar:
> >   all the example should be done on Mails # ... (few def as possible)
> Person and Calendar don't exists, I invented it just as examples. But
> each time I use it I show the correspondent XML Schema fragment. Isn't
> it enough?

Again, for me and you, YES. But for the occasional reader that reads it
for the first time you can expect a reaction such as: uh? where does
this Calendar comes from? did I miss something ... if you just add a
date as a sapare field in Mail he/she won't be lost. When you explain,
think worst :-)

> > Well when we will converge on the module naming convention we should
> > adopt all the same conventions for schemas too. I would not want to have
> > two different way to denote external components, being it modules or xsd
> > files.
> Actually it's hard to implement it in other ways. Schemas and modules
> are handled very differently. Using the same symbol will cause many
> ambiguity problems. Moreover I fill that the sharp simbol is well known
> to schema users since is the usual symbol used to reference types inside
> a schema document.

I was not clear. I meant that 

using M = XXX
schema S = YYY

XXX and YYY used the same conventions. That's all I meant.


More information about the Cduce-devel mailing list