Spec, schema

CSL Development
1

Head’s up: I’ve started a csl/doc/csl-spec.mdml file. My intension is
to use pandoc to generate syntax-highlighted HTML (thanks to Rintze
for help here), and also docbook, which I can pipe to an xslt to
extract the schema.

Note: I’m modifying the schema a bit as I go to clarify it in the
context of the spec doc.

Feel free to help, or offer suggestions.

Bruce

2

Three minor questions:

  • when the schema is extracted, it will become one single file, right?
    (unlike the files in the split branch)
  • which branch are you using to construct the spec? (split?)
  • were should further development of the schema take place? Still in the
    split branch?

Rintze

3

Three minor questions:

  • when the schema is extracted, it will become one single file,
    right? (unlike the files in the split branch)

Correct.

  • which branch are you using to construct the spec? (split?)
  • were should further development of the schema take place? Still in
    the split branch?

No. If this works, there will no longer be separate dev schemes. So
development happens directly on the spec.

I believe the spec is in trunk.

Bruce

4

Just a followup …

…

No. If this works, there will no longer be separate dev schemes. So
development happens directly on the spec.

My reasoning behind this is this makes it:

a) easier to produce the (HTML) output we want (rather than me to have
to write XSLT and do some other funky things).

b) allows us to clean up both the schema, and fill in the (natural
language) blanks.

c) offers more room to explain issues not directly related to the
schema (style hosting, etc.)

So my hope is it’s a quicker way to get both a tighter schema, and a
very clear (human readable) spec.

Here’s the link:

http://xbiblio.svn.sourceforge.net/viewvc/xbiblio/csl/doc/csl-spec.mdml?view=markup

I’m still trying to figure out the best way to visually do the
distinction between RNC schema fragments, and XML instance examples.
Perhaps using boxes with different visuals (say background colors)?
I’ll worry about this more once I get farther, and I figure out how to
compile RNC syntax highlighting into pandoc.

I also need to figure out the best way to deal with annotations.
Editors like oXygen will use them to present in-context help, so they
can be useful. But in the context of the human-readable spec, they’re
not as easy-to-read, and might be duplicative.

Finally, I’m contemplating splitting the document up; I’ll probably do
this, as using pandoc, I still still slurp them up into a single
document if we prefer.

Bruce

5

My questions were more about the short-term. Is it your goal to make the
switch to a literate spec before releasing CSL 0.9 and 1.0?

Rintze

6

Yes.

Well, at least for 1.0. We’ll just have to see whether we can do this
for 0.9 (which is probably going to be late).

Bruce