On Thu, Jun 25, 2009 at 3:34 PM, Bruce D'Arcus <bdarcus@gmail.com> wrote:
FYI, I added the style syntax doc to the svn as
csl/doc/csl-spec-z.mdml. It might provide a better foundation, but
we'd need:

1) to figure out how we want to deal with the schema. We could embed
the fragments as I've started to do, and/or add the complete schema to
the end.

I'm having some difficulties visualizing how a readible spec would look like if it contained a lot of schema fragments. I guess that when the style wizard is online, the spec will be mainly used by two groups:
a) users/style authors seeking ways to modify their styles beyond the scope of the style wizard (the size of this group will depend a lot on the wizard)
b) implementers of CSL processors

Group a doesn't really have to see any of the schema code. Basic knowledge of HTML/XML is arguably more widespread than the ability to read RNC (it took me quite some time to get into it), and showing schema code would probably just reduce readability for this group. Also, having to use the (fragmented) structure of the schema as the backbone of the spec might end up to be quite restrictive in handling topics. Group b on the other hand does need access to the schema to get the specifics right, but maybe clear use of the schema-terms in the spec will allow implementers to quickly jump from spec to schema (on http://www.zotero.org/support/dev/csl_syntax_summary this is already done to a certain extend by monospacing schema-terms). For both options I don't know what should happen with the comments/annotations in the schema. Maybe they could all be removed, once the spec covers everything? Maybe Frank has some wise words here, as he worked through the entire schema.
 
2) I started to attach explicit namespace prefixes to some of the
examples to avoid potential confusion; probably needs to be done
throughout

I do think this might confuse people in group a, as CSL styles generally don't include these prefixes.

3) if we use this as the basis, we ought to add contributor names
(beyond Rintze and I)?

Judging from the number of commits (a poor metric, I know), the users that made significant contributions seems limited to you, me and Julian Onions (Codec). The rest of the contributors are: Simon (3 edits), komrade (3), Richard Karnesky (2), tsherratt (1).

Rintze