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: Example [Was: Two things to strengthen the spec]


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>


mjf> OR I PREFER ONE LONG EXAMPLE SHOWING ALL THE PROSE DESCRIPTION IN
SECTION 2 WITH A SIMPLE INSTANCE OF EACH PART, WITHOUT mjf> PERHAPS ANY
FURTHER COMMENT
---------------------

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



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


Powered by eList eXpress LLC