.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] (). Particularly relevant are (which neither comments on usage nor specifies required and optional fields) and (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\ nm\ 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 .