.TH "scholdoc\-citeproc" "1" "2014-10-16" "0.6" ""
.SH NAME
.PP
scholdoc\-citeproc \- filter to resolve citations in a Pandoc/Scholdoc
document.
.SH SYNOPSIS
.PP
scholdoc\-citeproc [options] [file..]
.SH DESCRIPTION
.PP
Scholdoc\-citeproc is a fork of \f[C]pandoc\-citeproc\f[], meant to be
used with Scholdoc instead of Pandoc.
.PP
The \f[C]scholdoc\-citeproc\f[] executable has two modes, filter mode
and convert mode.
.SS Filter mode
.PP
Run without options, it acts as a filter that takes a JSON\-encoded
Pandoc/Scholdoc document, formats citations and adds a bibliography, and
returns a JSON\-encoded scholdoc document.
Citations will be resolved, and a bibliography will be appended to the
end of the document (unless the \f[C]suppress\-bibliography\f[] metadata
field is set to a true value).
If you wish the bibliography to have a section header, put the section
header at the end of your document.
(See the \f[C]pandoc_markdown\f[] (5) man page under \[lq]Citations\[rq]
for details on how to encode citations in pandoc's markdown.)
.PP
To process citations with scholdoc, call scholdoc\-citeproc as a filter:
.IP
.nf
\f[C]
scholdoc\ \-\-filter\ scholdoc\-citeproc\ input.md\ \-s\ \-o\ output.html
\f[]
.fi
.PP
The bibliography will be put into a pandoc \f[C]Div\f[] container with
class \f[C]references\f[].
.PP
scholdoc\-citeproc will look for the following metadata fields in the
input:
.PP
\f[C]bibliography\f[]: A path, or YAML list of paths, of bibliography
files to use.
These may be in any of the formats supported by bibutils.
.IP
.nf
\f[C]
Format\ \ \ \ \ \ \ \ \ \ \ \ File\ extension
\-\-\-\-\-\-\-\-\-\-\-\-\ \ \ \ \ \ \-\-\-\-\-\-\-\-\-\-\-\-\-\-
MODS\ \ \ \ \ \ \ \ \ \ \ \ \ \ .mods
BibLaTeX\ \ \ \ \ \ \ \ \ \ .bib
BibTeX\ \ \ \ \ \ \ \ \ \ \ \ .bibtex
RIS\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .ris
EndNote\ \ \ \ \ \ \ \ \ \ \ .enl
EndNote\ XML\ \ \ \ \ \ \ .xml
ISI\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ .wos
MEDLINE\ \ \ \ \ \ \ \ \ \ \ .medline
Copac\ \ \ \ \ \ \ \ \ \ \ \ \ .copac
JSON\ citeproc\ \ \ \ \ .json
\f[]
.fi
.PP
\f[C]references\f[]: A YAML list of references.
Each reference is a YAML object.
The format is essentially CSL JSON format.
Here is an example:
.IP
.nf
\f[C]
\-\ id:\ doe2006
\ \ author:
\ \ \ \ family:\ Doe
\ \ \ \ given:\ [John,\ F.]
\ \ title:\ Article
\ \ page:\ 33\-34
\ \ issued:
\ \ \ \ year:\ 2006
\ \ type:\ article\-journal
\ \ volume:\ 6
\ \ container\-title:\ Journal\ of\ Generic\ Studies
\f[]
.fi
.PP
The contents of fields will be interpreted as markdown when appropriate:
so, for example, emphasis and strong emphasis can be used in title
fileds.
Simple tex math will also be parsed and rendered appropriately.
.PP
\f[C]csl\f[] or \f[C]citation\-style\f[]: Path or URL of a CSL style
file.
If the file is not found relative to the working directory,
scholdoc\-citeproc will look in the \f[C]$HOME/.csl\f[] directory (or
\f[C]C:\\Users\\USERNAME\\AppData\\Roaming\\csl\f[] in Windows 7).
If this is left off, scholdoc\-citeproc will look for
\f[C]$HOME/.csl/chicago\-author\-date.csl\f[], and if this is not
present, it will use its own version of
\f[C]chicago\-author\-date.csl\f[].
.PP
\f[C]citation\-abbreviations\f[]: Path to a CSL abbreviations JSON file.
The format is described
here (http://citationstylist.org/2011/10/19/abbreviations-for-zotero-test-release).
Here is a short example:
.IP
.nf
\f[C]
{\ "default":\ {
\ \ \ \ "container\-title":\ {
\ \ \ \ \ \ \ \ \ \ \ \ "Lloyd\[aq]s\ Law\ Reports":\ "Lloyd\[aq]s\ Rep",
\ \ \ \ \ \ \ \ \ \ \ \ "Estates\ Gazette":\ "EG",
\ \ \ \ \ \ \ \ \ \ \ \ "Scots\ Law\ Times":\ "SLT"
\ \ \ \ }
\ \ }
}
\f[]
.fi
.PP
The metadata must contain either \f[C]references\f[] or
\f[C]bibliography\f[] or both as a source of references.
\f[C]csl\f[] and \f[C]citation\-abbreviations\f[] are optional.
If \f[C]csl\f[] is not provided, \f[C]chicago\-author\-date.csl\f[] will
be used by default.
.SS Convert mode
.PP
If the option \f[C]\-\-bib2yaml\f[] or \f[C]\-\-bib2json\f[] is used,
\f[C]scholdoc\-citeproc\f[] will not process citations; instead, it will
treat its input (from stdin or files) as a bibliography and convert it
either to a scholdoc YAML metadata section, suitable for inclusion in a
scholdoc document (\f[C]\-\-bib2yaml\f[]), or as a CSL JSON
bibliography, suitable for import to zotero (\f[C]\-\-bib2json\f[]).
.PP
The \f[C]\-\-format\f[] option can be used to specify the bibliography
format, though when files are used, \f[C]scholdoc\-citeproc\f[] can
generally guess this from the extension.
.PP
This mode supersedes the old \f[C]biblio2yaml\f[] program.
.SH OPTIONS
.TP
.B \f[C]\-h,\ \-\-help\f[]
Print usage information.
.RS
.RE
.TP
.B \f[C]\-V,\ \-\-version\f[]
Print version.
.RS
.RE
.TP
.B \f[C]\-y,\ \-\-bib2yaml\f[]
Convert bibliography to YAML suitable for inclusion in pandoc metadata.
.RS
.RE
.TP
.B \f[C]\-j,\ \-\-bib2json\f[]
Convert bibliography to CSL JSON suitable for import into Zotero.
.RS
.RE
.TP
.B \f[C]\-f\f[] \f[I]FORMAT\f[], \f[C]\-\-format=\f[]\f[I]FORMAT\f[]
Specify format of bibliography to be converted.
Legal values are \f[C]biblatex\f[], \f[C]bibtex\f[], \f[C]ris\f[],
\f[C]endnote\f[], \f[C]endnotexml\f[], \f[C]isi\f[], \f[C]medline\f[],
\f[C]copac\f[], \f[C]mods\f[], and \f[C]json\f[].
.RS
.RE
.SH NOTES
.SS General
.PP
If you use a biblatex database, closely follow the specifications in the
\[lq]Database Guide\[rq] section of the biblatex manual (currently
2.8a).
.PP
If you use a CSL\-YAML or CSL\-JSON database, or a CSL\-YAML metadata
section in your markdown document, follow the \[lq]Citation Style
Language 1.0.1 Language Specification\[rq]
(<http://citationstyles.org/downloads/specification.html>).
Particularly relevant are
<http://citationstyles.org/downloads/specification.html#appendix-iii-types>
(which neither comments on usage nor specifies required and optional
fields) and
<http://citationstyles.org/downloads/specification.html#appendix-iv-variables>
(which does contain comments).
.SS Titles: Title vs.\ Sentence Case
.PP
If you are using a bibtex or biblatex bibliography, then observe the
following rules:
.IP \[bu] 2
English titles should be in title case.
Non\-English titles should be in sentence case, and the \f[C]langid\f[]
field in biblatex should be set to the relevant language.
(The following values are treated as English: \f[C]american\f[],
\f[C]british\f[], \f[C]canadian\f[], \f[C]english\f[],
\f[C]australian\f[], \f[C]newzealand\f[], \f[C]USenglish\f[], or
\f[C]UKenglish\f[].)
.IP \[bu] 2
As is standard with bibtex/biblatex, proper names should be protected
with curly braces so that they won't be lowercased in styles that call
for sentence case.
For example:
.RS 2
.IP
.nf
\f[C]
title\ =\ {My\ Dinner\ with\ {Andre}}
\f[]
.fi
.RE
.IP \[bu] 2
In addition, words that should remain lowercase (or camelCase) should be
protected:
.RS 2
.IP
.nf
\f[C]
title\ =\ {Spin\ Wave\ Dispersion\ on\ the\ {nm}\ Scale}
\f[]
.fi
.PP
Though this is not necessary in bibtex/biblatex, it is necessary with
citeproc, which stores titles internally in sentence case, and converts
to title case in styles that require it.
Here we protect \[lq]nm\[rq] so that it doesn't get converted to
\[lq]Nm\[rq] at this stage.
.RE
.PP
If you are using a CSL bibliography (either JSON or YAML), then observe
the following rules:
.IP \[bu] 2
All titles should be in sentence case.
.IP \[bu] 2
Use the \f[C]language\f[] field for non\-English titles to prevent their
conversion to title case in styles that call for this.
(Conversion happens only if \f[C]language\f[] begins with \f[C]en\f[] or
is left empty.)
.IP \[bu] 2
Protect words that should not be converted to title case using this
syntax:
.RS 2
.IP
.nf
\f[C]
Spin\ wave\ dispersion\ on\ the\ <span\ class="nocase">nm</span>\ scale
\f[]
.fi
.RE
.SS Conference Papers, Published vs.\ Unpublished
.PP
For a formally published conference paper, use the biblatex entry type
\f[C]inproceedings\f[] (which will be mapped to CSL
\f[C]paper\-conference\f[]).
.PP
For an unpublished manuscript, use the biblatex entry type
\f[C]unpublished\f[] without an \f[C]eventtitle\f[] field (this entry
type will be mapped to CSL \f[C]manuscript\f[]).
.PP
For a talk, an unpublished conference paper, or a poster presentation,
use the biblatex entry type \f[C]unpublished\f[] with an
\f[C]eventtitle\f[] field (this entry type will be mapped to CSL
\f[C]speech\f[]).
Use the biblatex \f[C]type\f[] field to indicate the type, e.g.
\[lq]Paper\[rq], or \[lq]Poster\[rq].
\f[C]venue\f[] and \f[C]eventdate\f[] may be useful too, though
\f[C]eventdate\f[] will not be rendered by most CSL styles.
Note that \f[C]venue\f[] is for the event's venue, unlike
\f[C]location\f[] which describes the publisher's location; do not use
the latter for an unpublished conference paper.
.SH AUTHORS
.PP
Andrea Rossato, John MacFarlane, and Tim T.Y.
Lin.
.SH SEE ALSO
.PP
\f[C]scholdoc\f[] (1), \f[C]pandoc_markdown\f[] (5).
.PP
The scholdoc\-citeproc source code and all documentation may be
downloaded from <http://github.com/timtylin/scholdoc-citeproc/>.