GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  PANDOC-CITEPROC (1)

NAME

pandoc-citeproc - filter to resolve citations in a pandoc document.

CONTENTS

Synopsis
Description
     Filter mode
     Convert mode
Options
Notes
     General
     Titles: Title vs. Sentence Case
     Conference Papers, Published vs. Unpublished
Authors
See Also

SYNOPSIS

pandoc-citeproc [options] [file..]

DESCRIPTION

The C]pandoc-citeproc] executable has two modes, filter mode and convert mode.

    Filter mode

Run without options, it acts as a filter that takes a JSON-encoded Pandoc document, formats citations and adds a bibliography, and returns a JSON-encoded pandoc document. Citations will be resolved, and a bibliography will be appended to the end of the document (unless the C]suppress-bibliography] 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 C]pandoc_markdown] (5) man page under "Citations" for details on how to encode citations in pandoc[aq]s markdown.)

To process citations with pandoc, call pandoc-citeproc as a filter:
C]
pandoc --filter pandoc-citeproc input.md -s -o output.html
]

The bibliography will be put into a pandoc C]Div] container with class C]references].
pandoc-citeproc will look for the following metadata fields in the input:
C]bibliography]
  A path, or YAML list of paths, of bibliography files to use. These may be in any of the formats supported by bibutils.

Format File extension
BibLaTeX .bib
BibTeX .bibtex
Copac .copac
CSL JSON .json
CSL YAML .yaml
EndNote .enl
EndNote XML .xml
ISI .wos
MEDLINE .medline
MODS .mods
RIS .ris

Note that C].bib] can generally be used with both BibTeX and BibLaTeX files, but you can use C].bibtex] to force BibTeX.

C]references]
  A YAML list of references. Each reference is a YAML object. The format is essentially CSL JSON format. Here is an example:
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
]

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.
C]csl] or C]citation-style]
  Path or URL of a CSL style file. If the file is not found relative to the working directory, pandoc-citeproc will look in the C]$HOME/.csl] directory (or C]C:\Users\USERNAME\AppData\Roaming\csl] in Windows 7). If this is left off, pandoc-citeproc will look for C]$HOME/.csl/chicago-author-date.csl], and if this is not present, it will use its own version of C]chicago-author-date.csl].
C]link-citations]
  If this has a true value, citations in author-date and numerical styles will be hyperlinked to their corresponding bibliography entries. The default is not to add hyperlinks.
C]citation-abbreviations]
  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:
C]
{ "default": {
    "container-title": {
            "Lloyd[aq]s Law Reports": "Lloyd[aq]s Rep",
            "Estates Gazette": "EG",
            "Scots Law Times": "SLT"
    }
  }
}
]

C]locale]
  Locale to use in formatting citations. If this is not set, the locale is taken from the C]default-locale] attribute of the CSL file. C]en-US] is used if a locale is not specified in either the metadata or the CSL file.
C]suppress-bibliography]
  If this has a true value, the bibliography will be left off. Otherwise a bibliography will be added to the end of the document.
C]reference-section-title]
  If this has a value, a section header with this title will be added before the bibliography. Otherwise, the bibliography will simply be added to the end of the document. If C]reference-section-title] is not specified and the document ends with a section header, this final header will be treated as the bibliography header.
The metadata must contain either
C]references] or C]bibliography] or both as a source of references. C]csl] and C]citation-abbreviations] are optional. If C]csl] is not provided, C]chicago-author-date.csl] will be used by default.

    Convert mode

If the option C]--bib2yaml] or C]--bib2json] is used, C]pandoc-citeproc] will not process citations; instead, it will treat its input (from stdin or files) as a bibliography and convert it either to a pandoc YAML metadata section, suitable for inclusion in a pandoc document (C]--bib2yaml]), or as a CSL JSON bibliography, suitable for import to zotero (C]--bib2json]).

The C]--format] option can be used to specify the bibliography format, though when files are used, C]pandoc-citeproc] can generally guess this from the extension.

This mode supersedes the old C]biblio2yaml] program.

OPTIONS

C]-h, --help]
  Print usage information.
C]-V, --version]
  Print version.
C]-y, --bib2yaml]
  Convert bibliography to YAML suitable for inclusion in pandoc metadata.
C]-j, --bib2json]
  Convert bibliography to CSL JSON suitable for import into Zotero.
C]-f] I]FORMAT], C]--format=]I]FORMAT]
  Specify format of bibliography to be converted. Legal values are C]biblatex], C]bibtex], C]ris], C]endnote], C]endnotexml], C]isi], C]medline], C]copac], C]mods], and C]json].

NOTES

    General

If you use a biblatex database, closely follow the specifications in the "Database Guide" section of the biblatex manual (currently 2.8a).

If you use a CSL-YAML or CSL-JSON database, or a CSL-YAML metadata section in your markdown document, follow the "Citation Style Language 1.0.1 Language Specification" (<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).

    Titles: Title vs. Sentence Case

If you are using a bibtex or biblatex bibliography, then observe the following rules:
[bu] English titles should be in title case. Non-English titles should be in sentence case, and the C]langid] field in biblatex should be set to the relevant language. (The following values are treated as English: C]american], C]british], C]canadian], C]english], C]australian], C]newzealand], C]USenglish], or C]UKenglish].)
[bu] As is standard with bibtex/biblatex, proper names should be protected with curly braces so that they won[aq]t be lowercased in styles that call for sentence case. For example:
C]
title = {My Dinner with {Andre}}
]

[bu] In addition, words that should remain lowercase (or camelCase) should be protected:
C]
title = {Spin Wave Dispersion on the {nm} Scale}
]

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 "nm" so that it doesn[aq]t get converted to "Nm" at this stage.
If you are using a CSL bibliography (either JSON or YAML), then observe the following rules:
[bu] All titles should be in sentence case.
[bu] Use the C]language] field for non-English titles to prevent their conversion to title case in styles that call for this. (Conversion happens only if C]language] begins with C]en] or is left empty.)
[bu] Protect words that should not be converted to title case using this syntax:
C]
Spin wave dispersion on the <span class="nocase">nm</span> scale
]

    Conference Papers, Published vs. Unpublished

For a formally published conference paper, use the biblatex entry type C]inproceedings] (which will be mapped to CSL C]paper-conference]).

For an unpublished manuscript, use the biblatex entry type C]unpublished] without an C]eventtitle] field (this entry type will be mapped to CSL C]manuscript]).

For a talk, an unpublished conference paper, or a poster presentation, use the biblatex entry type C]unpublished] with an C]eventtitle] field (this entry type will be mapped to CSL C]speech]). Use the biblatex C]type] field to indicate the type, e.g. "Paper", or "Poster". C]venue] and C]eventdate] may be useful too, though C]eventdate] will not be rendered by most CSL styles. Note that C]venue] is for the event[aq]s venue, unlike C]location] which describes the publisher[aq]s location; do not use the latter for an unpublished conference paper.

AUTHORS

Andrea Rossato and John MacFarlane.

SEE ALSO

C]pandoc] (1), C]pandoc_markdown] (5).

The pandoc-citeproc source code and all documentation may be downloaded from <http://github.com/jgm/pandoc-citeproc/>.

Search for    or go to Top of page |  Section 1 |  Main Index


0.7.1.1 PANDOC-CITEPROC (1) 2015-06-10

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.