OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

relax-ng message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Subject: Re: Example [Was: Two things to strengthen the spec]

I think a single comprehensive example in Section 2 would be useful.

However, I think we also need to pay attention to the length of the spec. 
Although it's superficial, the number of pages in a spec does contribute to 
people's initial impression of its complexity.  Thus, I do think we should 
assume so basic level of understanding of XML, and XML Namespaces, and not 
attempt to incorporate a tutorial on these in the spec.

I also want to give priority to adding examples where there is least one 
reader who in fact found it hard to understand without an example, and 
would have been assisted by an example.

--On 18 July 2001 18:03 -0700 Michael Fitzgerald <mike@wyeast.net> wrote:

> Here is an initial example.
> I think Section 2, "Data Model," is clear and quite concise. I think
> anyone familiar with XML won't have any trouble with this section.
> Nevertheless, it could still be strengthened by adding examples and
> perhaps some definitions.
> At first glance you may think that such examples (below) are unnecessary,
> but if you try to see the augmented section through the eyes of a relative
> newcomer, or through the eyes of an old hand in a big hurry, I think you
> will agree that examples here does not insult the spec or the reader. A
> general pattern of tell them then show them most generally leaves no one
> behind in understanding.
> Links to where productions live and fuller explanations live are
> essential; however, propinquity [nearness] is a great convenience to
> readers.
> I am not suggesting that James and Murata-san must write all this extra
> stuff. Others on the TC can certainly help. I am happy to pitch in.
> Here is your section with my skeletal additions (mjf>). I haven't spent
> much time on the writing, which can be improved, but please note the
> placement:
> -------------------------
> ...
> A name consists of
> * a string representing the namespace URI; the empty string has special
> significance, representing the absence of any namespace
> * a string representing the local name; this string matches the NCName
> production of [XML Namespaces]
> mjf> [Definition: A namespace URI identifies a collection of XML names
> with a Uniform Resource Identifier or URI.
> mjf> For example, http://relaxng.org/ns/structure/0.9 is the namespace URI
> for RELAX NG. URIs may be either Uniform Resource mjf> Locators (URLs) or
> Uniform Resource Names (URNs). URIs are described in [RFC 2396]. XML
> namespaces are described in
> mjf> [XML Namespaces].]
> mjf> [Definition: A NCName is a non-colonized name or a name without a
> colon as opposed to a qualified name which has a
> mjf> colon. For example, div is an example of a NCName for a RELAX NG
> element. Compare [QName].]
> A context consists of
> * a base URI
> * a namespace map; this maps prefixes to namespace URIs, and also may
> specify a default namespace URI (as declared by the xmlns attribute)
> mjf> [Definition: A base URI.... See [XML Base].]
> An attribute consists of
> * a name
> * a string representing the value
> A string consists of a sequence of zero or more characters, where a
> character is as defined in [XML 1.0].
> mjf>
> mjf> [Example: <env:Body mustUnderstand="1">]
> mjf>
> ---------------------
> Because the examples and definitions are in blocks, a reader can more
> easily skip them if they are superfluous to that reader, without worrying
> about missing something.
> I am a firm believer that you can never say too many obvious things.
> Mike
> ------------------------------------------------------------------
> To unsubscribe from this elist send a message with the single word
> "unsubscribe" in the body to: relax-ng-request@lists.oasis-open.org

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [Elist Home]

Powered by eList eXpress LLC