spec

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.

  2. I started to attach explicit namespace prefixes to some of the
    examples to avoid potential confusion; probably needs to be done
    throughout

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

Thoughts?

Bruce

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

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

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

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 dev:csl_syntax_summary [Zotero Documentation]
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.

FWIW, I think the priority for the spec has to be implementers. It’s
only a temporary state of affairs that users ever need to see the XML,
much work with it.

So Frank, Andrea, and the Mendeley guys probably have the most
important perspectives on what this thing should look like. Feedback
now would be helpful.

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

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

OK, thanks.

Bruce

To get a vague sense of the two options, here’s the start of the
version based on the work on the zotero wiki:

http://www.users.muohio.edu/darcusb/citations/csl/spec1.html

At the moment, this includes no RNG fragments; only text, and example XML.

Here, OTOH, is the doc I started the other day, with include RNG and XML:

http://www.users.muohio.edu/darcusb/citations/csl/spec2.html

Bruce

One other thing …

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

My worry, though, is that developers do something stupid like forget
about the namespaces. That would mean valid styles with prefixes
likely wouldn’t work.

Bruce

One other thing …

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

My worry, though, is that developers do something stupid like forget
about the namespaces. That would mean valid styles with prefixes
likely wouldn’t work.

If there is at least one test in the test suite that covers the issue
you’re worrying over here, you can spare the clutter in the
specification (and the abusive language as well). A footnote or
parenthetical early in the spec that contains an explanation of
namespaces and thier importance, suitable for copy-pasting, should be
sufficient to cover this.

To get a vague sense of the two options, here’s the start of the
version based on the work on the zotero wiki:

http://www.users.muohio.edu/darcusb/citations/csl/spec1.html

At the moment, this includes no RNG fragments; only text, and example XML.

Here, OTOH, is the doc I started the other day, with include RNG and XML:

http://www.users.muohio.edu/darcusb/citations/csl/spec2.html

If the options are text without RNG versus text with RNG, I think the
former is more readable. None of the implementations perform
validation, the focus (for me at least) is more on getting individual
elements and attributes to do the right thing. I link to the relevant
section of the RNG would be useful, for quick reference. My two bits,
anyway. If I’ve misunderstood what these examples are meant to
represent (couldn’t find a reference to a choice between options
up-thread), please ignore this.

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 dev:csl_syntax_summary [Zotero Documentation]
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.

FWIW, I think the priority for the spec has to be implementers. It’s
only a temporary state of affairs that users ever need to see the XML,
much work with it.

So Frank, Andrea, and the Mendeley guys probably have the most
important perspectives on what this thing should look like. Feedback
now would be helpful.

Do you want feedback on the text itself, or only on the layout?

More the latter. Consider both the question of schema fragments or
not, as well as the document structure (as represented in the table of
contents*).

But you should also consider what you’d like to see in terms of
content, and how well the (fuller) content from the zotero wiki works
as a basis. In other words, should we start from that, and edit it
according to what criteria?

Bruce

  • Ultimately the TOC will probably get some JS magic.

That’s a reasonable point, but there’s one wrinkle:

The attributes in CSL are not namespaced. The elements are. Is it
misleading/confusing, then, if developers see “text” and “name”,
rather than the more correct “cs:text” and “name”?

Bruce

If there is at least one test in the test suite that covers the issue
you’re worrying over here, you can spare the clutter in the
specification (and the abusive language as well). A footnote or
parenthetical early in the spec that contains an explanation of
namespaces and thier importance, suitable for copy-pasting, should be
sufficient to cover this.

That’s a reasonable point, but there’s one wrinkle:

The attributes in CSL are not namespaced. The elements are. Is it
misleading/confusing, then, if developers see “text” and “name”,
rather than the more correct “cs:text” and “name”?

I don’t know. I’ve never studied XML, and I’ve never claimed to
understand how namespaces work. I don’t know what the cs: prefix
signifies, and until a failing test emerges, I’ll continue to assume
that it doesn’t affect anything at the implementation level … which
adds up to the conclusion that I don’t have much useful to say, I
suppose. Maybe someone with more formal training can comment.