.\" Automatically generated by Pandoc 2.13
.\"
.TH "citeproc" "1" "" "citeproc 0.6" ""
.hy
.SH NAME
.PP
citeproc - process citations using a CSL stylesheet.
.SH SYNOPSIS
.PP
\f[C]citeproc [options] [file]\f[R]
.SH DESCRIPTION
.PP
\f[C]citeproc\f[R] reads a JSON-encoded \f[C]Inputs\f[R] object from
\f[C]stdin\f[R] (or from a file if a filename is provided) and writes a
JSON-encoded \f[C]Result\f[R] object to \f[C]stdout\f[R].
This executable can be used to add citation processing to non-Haskell
projects.
.SH OPTIONS
.TP
\f[B]\f[CB]-s\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--style=\f[B]\f[R]\f[I]FILE\f[R]
Specify a CSL style to be used.
.TP
\f[B]\f[CB]-r\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--references=\f[B]\f[R]\f[I]FILE\f[R]
Specify a CSL JSON bibliography to be used as a source for references.
.TP
\f[B]\f[CB]a\f[B]\f[R] \f[I]FILE\f[R], \f[B]\f[CB]--abbreviations=\f[B]\f[R]\f[I]FILE\f[R]
Specify a CSL abbreviations file.
.TP
\f[B]\f[CB]l\f[B]\f[R] \f[I]LANG\f[R], \f[B]\f[CB]--lang=\f[B]\f[R]\f[I]LANG\f[R]
Specify a locale to override the style\[cq]s default.
A BCP 47 language tag is expected: for example, \f[C]en\f[R],
\f[C]de\f[R], \f[C]en-US\f[R], \f[C]fr-CA\f[R], \f[C]ug-Cyrl\f[R].
The unicode extension syntax (after \f[C]-u-\f[R]) may be used to
specify options for collation.
Here are some examples:
.RS
.IP \[bu] 2
\f[C]zh-u-co-pinyin\f[R] \[en] Chinese with the Pinyin collation.
.IP \[bu] 2
\f[C]es-u-co-trad\f[R] \[en] Spanish with the traditional collation
(with \f[C]Ch\f[R] sorting after \f[C]C\f[R]).
.IP \[bu] 2
\f[C]fr-u-kb\f[R] \[en] French with \[lq]backwards\[rq] accent sorting
(with \f[C]cot\['e]\f[R] sorting after \f[C]c\[^o]te\f[R]).
.IP \[bu] 2
\f[C]en-US-u-kf-upper\f[R] \[en] English with uppercase letters sorting
before lower (default is lower before upper).
.RE
.TP
\f[B]\f[CB]f\f[B]\f[R] \f[I]html|json\f[R], \f[B]\f[CB]--format=\f[B]\f[R]\f[I]html|json\f[R]
Specify the format to be used for the entries.
\f[C]html\f[R] (the default) uses HTML tags and entities for formatting.
\f[C]json\f[R] creates a structured JSON representation of a formatted
document.
.TP
\f[B]\f[CB]-h, --help\f[B]\f[R]
Print usage information.
.TP
\f[B]\f[CB]-V, --version\f[B]\f[R]
Print version.
.SH NOTES
.PP
The input JSON should have the structure:
.IP
.nf
\f[C]
{ \[dq]citations\[dq]:     [ ...list of citations... ],
  \[dq]references\[dq]:    [ ...list of references... ],
  \[dq]style\[dq]:         \[dq]<style>...</style>\[dq],
  \[dq]abbreviations\[dq]: { ...abbreviations... },
  \[dq]lang\[dq]:          \[dq]fr-FR\[dq] }
\f[R]
.fi
.PP
None of these fields is mandatory.
Instead of providing \f[C]references\f[R] in the input JSON, one can
specify a file containing a CSL JSON bibliography, using the
\f[C]--references\f[R] option on the command line.
Instead of providing a CSL stylesheet in the JSON, one can specify a
file using the \f[C]--style\f[R] option.
\f[C]--abbreviations\f[R] and \f[C]--lang\f[R] may also be used on the
command line to specify an abbreviations file or a locale.
(Command-line options always override any values given in the JSON
file.)
.PP
A citation is structured like this:
.IP
.nf
\f[C]
{ \[dq]citationID\[dq]: \[dq]foo\[dq],
  \[dq]citationItems\[dq]: [ ...list of citationItems... ],
  \[dq]citationNoteNumber\[dq]: 3 }
\f[R]
.fi
.PP
Only \f[C]citationItems\f[R] is necessary.
Alternatively, instead of
.IP
.nf
\f[C]
{ \[dq]citationItems\[dq]: [ ... ] }
\f[R]
.fi
.PP
one can just specify an array of items directly:
.IP
.nf
\f[C]
[ ... ]
\f[R]
.fi
.PP
A citation item is structured like this:
.IP
.nf
\f[C]
{ \[dq]id\[dq]:       \[dq]foo\[dq],
  \[dq]type\[dq]:     \[dq]suppress-author\[dq],
  \[dq]label\[dq]:    \[dq]page\[dq],
  \[dq]locator\[dq]:  \[dq]45\[dq],
  \[dq]prefix\[dq]:   \[dq]see \[dq],
  \[dq]suffix\[dq]:   \[dq] and others\[dq] }
\f[R]
.fi
.PP
Only \f[C]id\f[R] is mandatory.
If \f[C]type\f[R] is omitted, it will be assumed to be
\f[C]normal-cite\f[R] (other values are \f[C]suppress-author\f[R] and
\f[C]author-only\f[R]).
.PP
A reference is structured like this:
.IP
.nf
\f[C]
{
  \[dq]author\[dq]: [
    {
      \[dq]family\[dq]: \[dq]Aristotle\[dq]
    }
  ],
  \[dq]id\[dq]: \[dq]aristotle:prior\[dq],
  \[dq]issued\[dq]: {
    \[dq]date-parts\[dq]: [
      [
        1989
      ]
    ]
  },
  \[dq]publisher\[dq]: \[dq]Hackett\[dq],
  \[dq]publisher-place\[dq]: \[dq]Indianapolis\[dq],
  \[dq]title\[dq]: \[dq]Prior analytics\[dq],
  \[dq]translator\[dq]: [
    {
      \[dq]family\[dq]: \[dq]Smith\[dq],
      \[dq]given\[dq]: \[dq]Robin\[dq]
    }
  ],
  \[dq]type\[dq]: \[dq]book\[dq]
}
\f[R]
.fi
.PP
An abbreviations object has this form:
.IP
.nf
\f[C]
{ \[dq]default\[dq]: {
    \[dq]container-title\[dq]: {
            \[dq]Lloyd\[aq]s Law Reports\[dq]: \[dq]Lloyd\[aq]s Rep\[dq],
            \[dq]Estates Gazette\[dq]: \[dq]EG\[dq],
            \[dq]Scots Law Times\[dq]: \[dq]SLT\[dq]
    }
  }
}
\f[R]
.fi
.PP
The abbreviations will be substituted in the output only when the
\f[C]form\f[R] attribute for the style element that renders the variable
is set to \f[C]short\f[R].
.PP
The output JSON will have the structure:
.IP
.nf
\f[C]
{ \[dq]citations\[dq]:    [ ...list of strings... ],
  \[dq]bibliography\[dq]: [ ...list of arrays: item id and a string... ],
  \[dq]warnings\[dq]:     [ ...list of warnings... ]
}
\f[R]
.fi
.PP
The contents of the entries will be HTML by default, but if
\f[C]--format=json\f[R] is specified, it will be a structured
representation of formatted text.
.IP
.nf
\f[C]
[
  \[dq]\[em]\[em]\[em]. 1983b. \[lq]The Concept of Truth in Formalized Languages.\[rq] In \[dq],
  {
    \[dq]format\[dq]: \[dq]italics\[dq],
    \[dq]contents\[dq]: [
      \[dq]Logic, Semantics, Metamathematics\[dq]
    ]
  },
  \[dq], edited by John Corcoran, 152\[en]278. Indianapolis: Hackett.\[dq]
]
\f[R]
.fi
.PP
This representation can be used if you want to convert the result to a
format other than HTML.
.SH AUTHORS
.PP
John MacFarlane