I’ve set to work on a small manual for the processor that, so far,
covers the basic command set and the expected input formats. Comments
welcomed.
The doc has a temporary online home at
http://gsl-nagoya-u.net/http/pub/citeproc-doc.html. It has a look and
feel similar to the specification and pretty-printed schema docs, and
can be moved to citationstyles.org when the site is ready and if
that’s deemed appropriate.
Frank
I’ve set to work on a small manual for the processor that, so far,
covers the basic command set and the expected input formats.
Nice.
Comments welcomed.
My immediate response is that is seems odd to define the input format
in the processor docs. Should be a separate doc in my view.
Random comments, some directly about the details here, some about
larger issues …
{ “author” : [
{ “literal” : “Society for Putting Things on Top of Other Things” }
]
}
I’d much prefer simply “name” as the key; much more standard.
It might not be the best example. For the XML-expert Eric van der Vlist,
you’d put the “van der” in the family name field. That’s not to say there
might not be other people named Eric van der Vlist who appreciate
particle-logic. The main point of this example is that the particle fields
can contain multiple ‘words’.
Rintze
[snip]
As I’ve said a few times already, I don’t think Eric would consider
this an appropriate use of this new concept that Rintze has
introduced. The “van der” fragment is part of the family name.
Have changed this in the doc, thanks.
What does “sticky” mean?
Changed this, too.
For comparison, I’ve used “display-as-sort”.
Will think about using this.
Dates: I don’t really know what to say, since this is generally in
some flux. The basic logic seems fine. There just may be some issues
with datatypes worth considering. For example, should this …{ “year” : -200
}… be …
{ “year” : -0200
}…, and so match expectations associated with standard date datatypes?
In Javascript, that would produce a decimal value of -128 (it’s
interpreted as octal with the superfluous leading zero).
Also, just noting that the section doesn’t seem to allow things like
“2000, Feb/Mar” (ranges or compound dates)?
Nope. Would need to know how delimiters and collapsing work, what to
do when only partial data is presented, and probably some other stuff.
Can’t attempt to handle ranges until that sort of info is available
from CSL.
On:
“Note that only IDs may be used to identify items. The ID is an
arbitrary, system-dependent identifier, used by the locally customized
retrieveItem() and retrieveItems() methods to retrieve actual item
data.”I’m just going to flag this as one of those “bigger” issues that may
need adjustment later. Both Zotero and Mendeley have done a horrible
job of making the documents they create independent, and using local
identifiers is one reason.
The identifier could be a URI, or a URI could be derived from it.
That’s up to the client. Remember that citeproc-js is a Javascript
application, and Javascript itself has no net access and does not grok
file IO.
As a related followup:
“The retrieveItem() function is used by the processor to fetch
individual items from storage.”How? How abstract is this interface?
These are arbitrary functions that return meaningful Javascript arrays
that correspond to an ID. The integrator has a free hand in defining
them, so long as that one condition is satisfied.
For example, let’s imagine a different implementation than appears to
be contemplated above. Let’s imagine that “citations” get added to a
web application (blog; whatever) by URI (global, not local, ID), and
the data for formatting is gathered by running some SPARQL queries
against a few different endpoints. Would this be feasible as things
stand?The doc has a temporary online home at
http://gsl-nagoya-u.net/http/pub/citeproc-doc.html. It has a look and
feel similar to the specification and pretty-printed schema docs,What happened to the auto-generated API docs? Will this be a
supplement to those?
That may not have been the best idea I’ve had this year. 
and can be moved to citationstyles.org when the site is ready and if
that’s deemed appropriate.I don’t think implementation docs belong there (though certainly links
to them do).
Okay. Maybe Zotero can host it when the time comes.
…
Dates: I don’t really know what to say, since this is generally in
some flux. The basic logic seems fine. There just may be some issues
with datatypes worth considering. For example, should this …{ “year” : -200
}… be …
{ “year” : -0200
}…, and so match expectations associated with standard date datatypes?
In Javascript, that would produce a decimal value of -128 (it’s
interpreted as octal with the superfluous leading zero).
Yeah, just depends what we want input to conform to: internal
datatypes, or more generic standard ones. As I said, this is in
general a work-in-progress, so we’ll have to feel our way through it.
…
What happened to the auto-generated API docs? Will this be a
supplement to those?That may not have been the best idea I’ve had this year.
I think the API docs ARE a good idea; tends to be what developers look for.
and can be moved to citationstyles.org when the site is ready and if
that’s deemed appropriate.I don’t think implementation docs belong there (though certainly links
to them do).Okay. Maybe Zotero can host it when the time comes.
Yup; makes sense. Could also be broken up and added to the bitbucket wiki.
Bruce
A simpler, more general, approach is to call it “display-rule” and
assume a default of “invert” and another option of “as sorted”.
BTW, we should probably all double-check this thread:
http://forums.zotero.org/discussion/2875/nonwestern-name-ordering-in-bibliographies/
Bruce
I think this is the key post:
… and that we’re probably OK (though that poster was thinking about
Asian names mostly; not Dutch ;-)).
Bruce