[cduce-devel] preliminary XML Schema documentation
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