citeproc-0.9: man/citeproc.1

.\" Automatically generated by Pandoc 3.6
.\"
.TH "citeproc" "1" "" "citeproc 0.8.1.1"
.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\[cq]s 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 \[lq]backwards\[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
{ \[dq]citations\[dq]:     [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]citations...\f[R] ],
  \[dq]references\[dq]:    [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]references...\f[R] ],
  \[dq]style\[dq]:         \[dq]<style>...</style>\[dq],
  \[dq]abbreviations\[dq]: { \f[B]...abbreviations...\f[R] },
  \[dq]lang\[dq]:          \[dq]fr\-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
{ \[dq]citationID\[dq]: \[dq]foo\[dq],
  \[dq]citationItems\[dq]: [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]citationItems...\f[R] ],
  \[dq]citationNoteNumber\[dq]: 3 }
.EE
.PP
Only \f[CR]citationItems\f[R] is necessary.
Alternatively, instead of
.IP
.EX
{ \[dq]citationItems\[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
{ \[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] }
.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
{
  \[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]
}
.EE
.PP
An abbreviations object has this form:
.IP
.EX
{ \[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]
    }
  }
}
.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
{ \[dq]citations\[dq]:    [ \f[B]...list\f[R] \f[B]of\f[R] \f[B]strings...\f[R] ],
  \[dq]bibliography\[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] ],
  \[dq]warnings\[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. \[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]
]
.EE
.PP
This representation can be used if you want to convert the result to a
format other than HTML.
.SH AUTHORS
John MacFarlane