=head1 NAME

pandoc-citeproc-preamble - insert a preamble before pandoc-citeproc's bibliography

=head1 SYNOPSIS

B<pandoc-citeproc-preamble>

=head1 DESCRIPTION

B<pandoc-citeproc-preamble> is a JSON filter for pandoc(1) which
inserts a preamble before the output that the pandoc-citeproc(1)
filter appends to the document.  This preamble might include a heading
(e.g. "Bibliography") and/or raw markup to format the bibliography for
the output format.

=head1 USAGE

Add B<--filter pandoc-citeproc-preamble> somewhere after B<--filter
pandoc-citeproc>, e.g.

=over 4

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

=back

=head1 FILES

=over 4

=item ~/.pandoc/citeproc-preamble/default.I<FORMAT>

Default citeproc preamble for Pandoc output format I<FORMAT>
(e.g. "latex").

=back

To override this, you can set document metadata like this:

=over 4

    % pandoc ... --filter pandoc-citeprocpreamble \
        -M citeproc-preamble=~/mypreamble.tex ...

=back

=head1 RATIONALE

One motivation for authoring with Pandoc is that one's input files are
agnostic with regard to the output format to which they will
eventually be compiled.  For example, it should not be necessary to
include LaTeX code in one's input file in order to format the
bibliography.  The input file might also be compiled to HTML.

However, when compiling to PDF, formatting code is usually required in
order to have the entries of pandoc-citeproc'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-citeproc(1) doesn't provide any facility to add
formatting control code to its output, B<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.

=head1 AUTHOR

Sean Whitton <spwhitton@spwhitton.name>

=head1 SEE ALSO

pandoc(1), pandoc-citeproc(1)