- From: Fabian Ritzmann <Fabian.Ritzmann@Sun.COM>
- Date: Thu, 13 Jul 2006 19:26:44 +0300
- To: Bijan Parsia <bparsia@cs.man.ac.uk>
- Cc: public-ws-policy@w3.org
Bijan Parsia wrote: > On Jul 13, 2006, at 7:24 AM, Fabian Ritzmann wrote: >> Bijan Parsia wrote: >> >>> As an implementor, I prefer the normative portions of the spec to be >>> clear, clean, and compact. Interleaving examples can be *very* >>> confusing and wearing. Plus, in the current document, it's somewhat >>> ambiguous as to what is normative, since all the "for examples" are >>> embedded in the specification. Examples are used in places where, >>> imho, it's a bit silly, like for Associative, Commutative, etc. >> >> Personally, I'd prefer to have a concise example even for the trivial >> cases. I find it easier to understand when I have formatted XML > > But these aren't about how to write a document, but on how "all" and > "exactly one" are commutative. I mean, the examples are schematic *anyway*! IMHO, that's not a bad thing. >>> If we are going to have examples of every bit of the spec in *this* >>> spec, rather than in the primer, I would prefer that it be localized >>> as was done in the RDF Revised Syntax: >>> <http://www.w3.org/TR/rdf-syntax-grammar/> >>> The "example of every construct" occurs in section 2: >>> <http://www.w3.org/TR/rdf-syntax-grammar/#section-Syntax> >>> (Which is a much better intro than the actual RDF primer.) >>> If we *do* want examples connected to the spec, why not just have >>> links to the appropriate sections of the primer? >> >> I don't feel strongly where exactly the examples should be placed and >> how they should be formatted, but I'd rather keep them in the spec >> itself. Constant cross-referencing between two documents is too >> inconvenient. > > Do you feel cross referencing between two parts of the same document is > too inconvenient as well? I guess it depends, but the document you are quoting is looking good to me. Fabian -- Fabian Ritzmann Sun Microsystems, Inc. Stella Business Park Phone +358-9-525 562 96 Lars Sonckin kaari 12 Fax +358-9-525 562 52 02600 Espoo Email Fabian.Ritzmann@Sun.COM Finland
Received on Thursday, 13 July 2006 16:26:54 UTC