add manpage

1 files changed, 76 insertions, 0 deletions

diff --git a/pandoc-citeproc-preamble.1.pod b/pandoc-citeproc-preamble.1.pod
new file mode 100644
index 0000000..521988e
--- /dev/null
+++ b/pandoc-citeproc-preamble.1.pod
@@ -0,0 +1,76 @@
+=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)