37
edits
Changes
→Bibliographic record format: excerpt from the spec
Of course you cannot throw any bibliographic record format into a CSL-Processor but you must use the [http://citationstyles.org/downloads/specification.html#appendices field names defined in the CSL 1.0 specification]. Some of the fields are repeatable and have an interal structure [http://gsl-nagoya-u.net/http/pub/citeproc-doc.html#data-input as described here].
=== CSL record format ===
Derived from the CSL 1.0 specification and the citeproc-js documentation a CSL record can be defined as a follows in incomplete Backus-Naur-Form and additional description:
A record is a JSON object with unique keys of three kinds (VAR, NAME, DATE, and TYPE):
'''(1)''' <tt>RECORD := '{' { STD ':' STD_VAL | NAME ':' NAME_VAL | DATE ':' DATE_VAL | TYPE }* '}'</tt> (plus comma as seperator)
A <tt>STD</tt> is a standard variable name as listed at http://citationstyles.org/downloads/specification.html#standard-variables.
'''(2)''' <tt>STD := '"abstract"' | '"annote"' | '"archive"' | ... </tt>
A <tt>NAME</tt> is a name variable name as listed at http://citationstyles.org/downloads/specification.html#name-variables.
'''(3)''' <tt>NAME := '"author"' | '"editor"' | ... </tt>
A <tt>DATE</tt> is a date variable name as listed at http://citationstyles.org/downloads/specification.html#date-variables.
'''(4)''' <tt>NAME := '"accessed"' | '"container"' | ... </tt>
A <tt>STD_VAL</tt> is simple JSON string
'''(5)''' <tt>STD_VAL := JSON_STRING</tt> (see JSON standard)
A <tt>TYPE</tt> contains a value from the types listed at http://citationstyles.org/downloads/specification.html#appendix-ii-types
'''(6)''' <tt>TYPE := '"type"' ':' ( '"article"' | '"book"' | ... )</tt>
A <tt>NAME_VAL</tt> is non-empty JSON array of JSON objects with <tt>NAME_PART</tt> keys and simple JSON string values:
'''(7)''' <tt>NAME_VAL := '[' ( '{' NAME_PART ':' JSON_STRING | STATIC_ORDERING '}' )+ ']'</tt> (plus comma as seperator)
A <tt>NAME_PART</tt> is variable name is one of
'''(8)''' <tt>NAME_PART := '"family"' | '"given"' | '"suffix"' | '"non-dropping-particle"' | '"dropping-particle"'</tt>
In addition you can add <tt>STATIC_ORDERING</tt> as part of the <tt>NAME_VAL</tt> to flag that a name is always displayed with the family name first ("non-Byzantine" names):
'''(9)''' <tt>STATIC_ORDERING := '"static-ordering"' ':' ANY_TRUE_JSON_VALUE</tt> (TODO: what is ANY_TRUE_JSON_VALUE?)
A <tt>DATE_VAL</tt> is a JSON object which contains at least a <tt>DATE_PARTS</tt> element and optionally a <tt>SEASON_VAL</tt> element:
'''(10)''' <tt>NAME_VAL := '{' '"date-parts"' ':' DATE_PARTS ( ',' '"season"' ':' SEASON_VAL )? '}'</tt>
A <tt>DATE_PARTS</tt> is is a nested JSON array containing a start date and optional end date, each of which consists of a year, an optional month and an optional day, in that order if present.
'''(11a)''' <tt>DATE_PARTS := '[' DATE ( ',' DATE )? ']'</tt> <br/>
'''(11b)''' <tt>DATE := '[' YEAR ( ',' MONTH ( ',' DAY )? )? ']'</tt> <br/>
'''(11c)''' <tt>YEAR := JSON_STRING | JSON_INTEGER</tt> (string must contain an interger. Number must not be zero)<br/>
'''(11d)''' <tt>MONTH := JSON_STRING | JSON_INTEGER</tt> (1 to 12)<br/>
'''(11e)''' <tt>DAY := JSON_STRING | JSON_INTEGER</tt> (1 to 31)<br/>
A <tt>SEASON_VAL</tt> should be one of 1 to 4 or a fixed JSON string:
'''(12)''' <tt>SEASON_VAL := '"1"' | '"2"' | '"3"' | '"4"' | JSON_STRING</tt>
The [http://gsl-nagoya-u.net/http/pub/citeproc-doc.html#dirty-tricks dirty-tricks fields of citeproc-js] are ''not valid'' CSL. Please clean your input data before feeding it to a CSL processor if you want to get sane citations.
=== Other record formats ===
If you want to use some other format (BibTeX, RIS, MARC, MODS, Bibliographic Ontology etc.) you go this way:
Record in your format -> some miracle occurs -> record in CSL format -> CSL-Processor -> Citation
Please replace "some miracle occurs" with the conversion service of your choice, for instance Zotero or some library software hacks that libraries tend to use. There is nothing wrong with specific bibliographic formats but its not their purpose to create citations (counterexamples: BibTeX and RIS).
== Embedding CSL records in twitter annotations ==