Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/spwhitton/pandoc-citeproc-preamble

Insert a preamble before pandoc-citeproc's bibliography
https://github.com/spwhitton/pandoc-citeproc-preamble

Last synced: 18 days ago
JSON representation

Insert a preamble before pandoc-citeproc's bibliography

Awesome Lists containing this project

README 

        
# pandoc-citeproc-preamble



## Synopsis



pandoc-citeproc-preamble is a JSON filter for [Pandoc][] which inserts a

preamble before the output that Pandoc's citeproc filter appends to the

document.  This preamble might include a heading (e.g. "Bibliography") and raw

markup to format the bibliography for the output format.



[Pandoc]: http://pandoc.org/ "Pandoc home page"



## Installation



Users of Debian 10 or later or Ubuntu 17.04 or later: `apt-get install

pandoc-citeproc-preamble`.  Users of Debian 9: enable

[backports][backports], and then `apt-get install -t stretch-backports

pandoc-citeproc-preamble`.



Otherwise, pandoc-citeproc-preamble uses the standard Haskell

toolchain and is available from Hackage, so you should just be able to

`cabal install pandoc-citeproc-preamble`.



If you are not a Haskell programmer, you might find it easier to



1. install [Stack][];

2. ensure that `~/.local/bin` is in your shell's PATH

3. run `stack install pandoc-citeproc-preamble`.



[backports]: https://backports.debian.org/Instructions/

[Stack]: https://github.com/commercialhaskell/stack



## Usage



Add `--filter pandoc-citeproc-preamble` somewhere after `--citeproc`, e.g.



    $ pandoc -s --citeproc --bibliography=~/doc/mine.bib --filter pandoc-citeproc-preamble ~/doc/my_essay.mdwn -o ~/my_essay.pdf



In this case, since the output format is LaTeX,

pandoc-citeproc-preamble will look for the preamble in the file

`data_dir/citeproc-preamble/default.latex` where `data_dir` is your

Pandoc user data directory, as reported by `pandoc --version`.  You

may specify a different preamble by setting document metadata like this:



    $ pandoc ... --filter pandoc-citeproc-preamble -M citeproc-preamble=~/my_preamble.tex ...



Please see "Rationale", below, for why it would defeat the purpose of

this script to include a value for `citeproc-preamble` in your input

file's YAML metadata block.



### Example preamble file



Please see my [~/.pandoc/citeproc-preamble/default.latex][], which

was inspired by [this guide][].



[~/.pandoc/citeproc-preamble/default.latex]: https://git.spwhitton.name/?p=dotfiles.git;a=blob;f=.pandoc/citeproc-preamble/default.latex;hb=HEAD "my default preamble"



[this guide]: http://kieranhealy.org/blog/archives/2014/01/23/plain-text/ "Plain Text, Papers, Pandoc"



## Rationale



One motivation for authoring with Pandoc is that one's input files are

agnostic with regard to the output format they will eventually be

compiled to: it should not be necessary to include in one's input

file, for example, LaTeX code to format the bibliography.



When compiling to PDF (which is probably the most common case for users of

Pandoc's citeproc filter), formatting code is usually required to have the

entries of Pandoc's bibliography line up with each other; by default, all

entries except the first will be indented.  Another common customisation is to

set up a [hanging indent][] for bibliography entries.



Since Pandoc's citeproc filter doesn't provide any facility to add formatting

control code to its output, pandoc-citeproc-preamble is necessary to avoid the

user being forced to add their control code to the end of their input files,

thereby losing the input file's agnosticity with regard to output format.



[hanging indent]: http://www.computerhope.com/jargon/h/hanginde.htm "description of hanging indent"



## Bugs



Please report bugs by e-mail to ``.



## License



Copyright (C) 2015-2016, 2019  Sean Whitton



pandoc-citeproc-preamble is free software: you can redistribute it

and/or modify it under the terms of the GNU General Public License as

published by the Free Software Foundation, either version 3 of the

License, or (at your option) any later version.



pandoc-citeproc-preamble is distributed in the hope that it will be

useful, but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

General Public License for more details.



You should have received a copy of the GNU General Public License

along with pandoc-citeproc-preamble.  If not, see

[](http://www.gnu.org/licenses/).