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]

James Clark wrote:
>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 can understand your concern about turning the spec into another tutorial.
I don't want you to do that either. I suggested block definitions as an
enhancement to aid understanding of a broader audience beyond the XML
cognoscenti, making the spec easy to grasp by someone who may be new to XML.
They will appreciate it. But I concede that the tutorial succeeds well for
this imagined broad audience already. Nonetheless, I believe block
definitions would only add about 1-2 pages to the spec's length. Not a dear
price to pay.

>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.

I read: let's add an example if there is a reason to do so.

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

Powered by eList eXpress LLC