citeproc-0.13: man/citeproc.1

.\" Automatically generated by Pandoc 3.8.3
.\"
.TH "citeproc" "1" "" "citeproc 0.12"
.SH NAME
citeproc \- process citations using a CSL stylesheet.
.SH SYNOPSIS
\f[CR]citeproc [options] [file]\f[R]
.SH DESCRIPTION
\f[CR]citeproc\f[R] reads a JSON\-encoded \f[CR]Inputs\f[R] object from
\f[CR]stdin\f[R] (or from a file if a filename is provided) and writes a
JSON\-encoded \f[CR]Result\f[R] object to \f[CR]stdout\f[R].
This executable can be used to add citation processing to non\-Haskell
projects.
.SH OPTIONS
.TP
\f[CR]\-s\f[R] \f[I]FILE\f[R], \f[CR]\-\-style=\f[R]\f[I]FILE\f[R]
Specify a CSL style to be used.
.TP
\f[CR]\-r\f[R] \f[I]FILE\f[R], \f[CR]\-\-references=\f[R]\f[I]FILE\f[R]
Specify a CSL JSON bibliography to be used as a source for references.
.TP
\f[CR]a\f[R] \f[I]FILE\f[R], \f[CR]\-\-abbreviations=\f[R]\f[I]FILE\f[R]
Specify a CSL abbreviations file.
.TP
\f[CR]l\f[R] \f[I]LANG\f[R], \f[CR]\-\-lang=\f[R]\f[I]LANG\f[R]
Specify a locale to override the style\(cqs default.
A BCP 47 language tag is expected: for example, \f[CR]en\f[R],
\f[CR]de\f[R], \f[CR]en\-US\f[R], \f[CR]fr\-CA\f[R],
\f[CR]ug\-Cyrl\f[R].
The unicode extension syntax (after \f[CR]\-u\-\f[R]) may be used to
specify options for collation.
Here are some examples:
.RS
.IP \(bu 2
\f[CR]zh\-u\-co\-pinyin\f[R] \(en Chinese with the Pinyin collation.
.IP \(bu 2
\f[CR]es\-u\-co\-trad\f[R] \(en Spanish with the traditional collation
(with \f[CR]Ch\f[R] sorting after \f[CR]C\f[R]).
.IP \(bu 2
\f[CR]fr\-u\-kb\f[R] \(en French with \(lqbackwards\(rq accent sorting
(with \f[CR]coté\f[R] sorting after \f[CR]côte\f[R]).
.IP \(bu 2
\f[CR]en\-US\-u\-kf\-upper\f[R] \(en English with uppercase letters
sorting before lower (default is lower before upper).
.RE
.TP
\f[CR]f\f[R] \f[I]html|json\f[R], \f[CR]\-\-format=\f[R]\f[I]html|json\f[R]
Specify the format to be used for the entries.
\f[CR]html\f[R] (the default) uses HTML tags and entities for
formatting.
\f[CR]json\f[R] creates a structured JSON representation of a formatted
document.
.TP
\f[CR]\-\-link\-citations\f[R]
Enable hyperlinking of citations to the bibliography.
.TP
\f[CR]\-\-link\-bibliography\f[R]
Enable automatic linkification of any identifiers (DOI, PMCID, PMID, or
URL) appearing in a bibliography entry.
When an entry has a DOI, PMCID, PMID, or URL available but none of these
are rendered by the style, add a link to the title (or, if no title is
present, the whole entry), using the URL for the DOI, PMCID, PMID, or
URL (in that order of priority).
.TP
\f[CR]\-h, \-\-help\f[R]
Print usage information.
.TP
\f[CR]\-V, \-\-version\f[R]
Print version.
.SH NOTES
The input JSON should have the structure:
.IP
.EX
{ \(dqcitations\(dq:     [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]citations...\f[R] ],
  \(dqreferences\(dq:    [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]references...\f[R] ],
  \(dqstyle\(dq:         \(dq<style>...</style>\(dq,
  \(dqabbreviations\(dq: { \f[B]...abbreviations...\f[R] },
  \(dqlang\(dq:          \(dqfr\-FR\(dq }
.EE
.PP
None of these fields is mandatory.
Instead of providing \f[CR]references\f[R] in the input JSON, one can
specify a file containing a CSL JSON bibliography, using the
\f[CR]\-\-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[CR]\-\-style\f[R] option.
\f[CR]\-\-abbreviations\f[R] and \f[CR]\-\-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
.EX
{ \(dqcitationID\(dq: \(dqfoo\(dq,
  \(dqcitationResetPosition\(dq: \f[B]false\f[R],
  \(dqcitationItems\(dq: [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]citationItems...\f[R] ],
  \(dqcitationNoteNumber\(dq: 3 }
.EE
.PP
Only \f[CR]citationItems\f[R] is necessary.
.PP
\f[CR]citationResetPosition\f[R] controls whether position information
is to be reset before the citation is processed (which affects whether
full citations or abbreviated forms are used, in some styles).
.PP
Alternatively, instead of
.IP
.EX
{ \(dqcitationItems\(dq: [ \f[B]...\f[R] ] }
.EE
.PP
one can just specify an array of items directly:
.IP
.EX
[ \f[B]...\f[R] ]
.EE
.PP
A citation item is structured like this:
.IP
.EX
{ \(dqid\(dq:       \(dqfoo\(dq,
  \(dqtype\(dq:     \(dqsuppress\-author\(dq,
  \(dqlabel\(dq:    \(dqpage\(dq,
  \(dqlocator\(dq:  \(dq45\(dq,
  \(dqprefix\(dq:   \(dqsee \(dq,
  \(dqsuffix\(dq:   \(dq and others\(dq }
.EE
.PP
Only \f[CR]id\f[R] is mandatory.
If \f[CR]type\f[R] is omitted, it will be assumed to be
\f[CR]normal\-cite\f[R] (other values are \f[CR]suppress\-author\f[R]
and \f[CR]author\-only\f[R]).
.PP
A reference is structured like this:
.IP
.EX
{
  \(dqauthor\(dq: [
    {
      \(dqfamily\(dq: \(dqAristotle\(dq
    }
  ],
  \(dqid\(dq: \(dqaristotle:prior\(dq,
  \(dqissued\(dq: {
    \(dqdate\-parts\(dq: [
      [
        1989
      ]
    ]
  },
  \(dqpublisher\(dq: \(dqHackett\(dq,
  \(dqpublisher\-place\(dq: \(dqIndianapolis\(dq,
  \(dqtitle\(dq: \(dqPrior analytics\(dq,
  \(dqtranslator\(dq: [
    {
      \(dqfamily\(dq: \(dqSmith\(dq,
      \(dqgiven\(dq: \(dqRobin\(dq
    }
  ],
  \(dqtype\(dq: \(dqbook\(dq
}
.EE
.PP
An abbreviations object has this form:
.IP
.EX
{ \(dqdefault\(dq: {
    \(dqcontainer\-title\(dq: {
            \(dqLloyd\(aqs Law Reports\(dq: \(dqLloyd\(aqs Rep\(dq,
            \(dqEstates Gazette\(dq: \(dqEG\(dq,
            \(dqScots Law Times\(dq: \(dqSLT\(dq
    }
  }
}
.EE
.PP
The abbreviations will be substituted in the output only when the
\f[CR]form\f[R] attribute for the style element that renders the
variable is set to \f[CR]short\f[R].
.PP
The output JSON will have the structure:
.IP
.EX
{ \(dqcitations\(dq:    [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]strings...\f[R] ],
  \(dqbibliography\(dq: [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]arrays:\f[R] \f[B]item\f[R] \f[B]id\f[R] \f[B]and\f[R] \f[B]a\f[R] \f[B]string...\f[R] ],
  \(dqwarnings\(dq:     [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]warnings...\f[R] ]
}
.EE
.PP
The contents of the entries will be HTML by default, but if
\f[CR]\-\-format=json\f[R] is specified, it will be a structured
representation of formatted text.
.IP
.EX
[
  \(dq\(em\(em\(em. 1983b. \(lqThe Concept of Truth in Formalized Languages.\(rq In \(dq,
  {
    \(dqformat\(dq: \(dqitalics\(dq,
    \(dqcontents\(dq: [
      \(dqLogic, Semantics, Metamathematics\(dq
    ]
  },
  \(dq, edited by John Corcoran, 152\(en278. Indianapolis: Hackett.\(dq
]
.EE
.PP
This representation can be used if you want to convert the result to a
format other than HTML.
.SH AUTHORS
John MacFarlane