# spec

**URL:** <https://discourse.citationstyles.org/t/spec/671>\
**Category:** CSL Development\
**Created:** [June 25, 2009, 1:34pm UTC](https://discourse.citationstyles.org/t/spec/671 "2009-06-25T13:34:29Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [June 25, 2009, 1:34pm UTC](https://discourse.citationstyles.org/t/spec/671/1 "2009-06-25T13:34:29Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Rintze\_Zelle](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/rintze_zelle/32/175_2.png) [@Rintze\_Zelle](https://discourse.citationstyles.org/u/Rintze_Zelle)\
**Post date:** [June 25, 2009, 7:45pm UTC](https://discourse.citationstyles.org/t/spec/671/2 "2009-06-25T19:45:23Z")

</div>

> 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](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

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [June 25, 2009, 8:01pm UTC](https://discourse.citationstyles.org/t/spec/671/3 "2009-06-25T20:01:29Z")

</div>

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

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

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [June 25, 2009, 8:25pm UTC](https://discourse.citationstyles.org/t/spec/671/4 "2009-06-25T20:25:27Z")

</div>

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](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](http://www.users.muohio.edu/darcusb/citations/csl/spec2.html)

Bruce

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [June 25, 2009, 8:29pm UTC](https://discourse.citationstyles.org/t/spec/671/5 "2009-06-25T20:29:35Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Frank\_Bennett](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/frank_bennett/32/198_2.png) [@Frank\_Bennett](https://discourse.citationstyles.org/u/Frank_Bennett)\
**Post date:** [June 25, 2009, 8:52pm UTC](https://discourse.citationstyles.org/t/spec/671/6 "2009-06-25T20:52:38Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Frank\_Bennett](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/frank_bennett/32/198_2.png) [@Frank\_Bennett](https://discourse.citationstyles.org/u/Frank_Bennett)\
**Post date:** [June 25, 2009, 9:22pm UTC](https://discourse.citationstyles.org/t/spec/671/7 "2009-06-25T21:22:13Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Frank\_Bennett](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/frank_bennett/32/198_2.png) [@Frank\_Bennett](https://discourse.citationstyles.org/u/Frank_Bennett)\
**Post date:** [June 25, 2009, 9:23pm UTC](https://discourse.citationstyles.org/t/spec/671/8 "2009-06-25T21:23:56Z")

</div>

> > > 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]](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.
> 
> 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?

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [June 25, 2009, 10:07pm UTC](https://discourse.citationstyles.org/t/spec/671/9 "2009-06-25T22:07:15Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Bruce\_D\_Arcus1](https://avatars.discourse-cdn.com/v4/letter/b/4bbf92/32.png) [@Bruce\_D\_Arcus1](https://discourse.citationstyles.org/u/Bruce_D_Arcus1)\
**Post date:** [June 25, 2009, 10:10pm UTC](https://discourse.citationstyles.org/t/spec/671/10 "2009-06-25T22:10:01Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Frank\_Bennett](https://yyz1.discourse-cdn.com/flex029/user_avatar/discourse.citationstyles.org/frank_bennett/32/198_2.png) [@Frank\_Bennett](https://discourse.citationstyles.org/u/Frank_Bennett)\
**Post date:** [June 25, 2009, 10:28pm UTC](https://discourse.citationstyles.org/t/spec/671/11 "2009-06-25T22:28:03Z")

</div>

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