add manpage

4 files changed, 82 insertions, 2 deletions

diff --git a/debian/changelog b/debian/changelog
index e727eb2..01159b7 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -2,7 +2,8 @@ pandoc-citeproc-preamble (1.2.3) UNRELEASED; urgency=medium
 
   * Convert changelog to Debian's format.
   * First upload to Debian: add debian/ subdirectory.
-  * New examples/ directory.
+  * Add examples/ directory.
+  * Add manpage (only installed by Debian package at present).
 
  -- Sean Whitton <spwhitton@spwhitton.name>  Sun, 29 Jan 2017 11:00:07 -0700
 
diff --git a/debian/manpages b/debian/manpages
new file mode 100644
index 0000000..0512277
--- /dev/null
+++ b/debian/manpages
@@ -0,0 +1 @@
+pandoc-citeproc-preamble.1
diff --git a/debian/rules b/debian/rules
index 42f7d2b..2a8d309 100755
--- a/debian/rules
+++ b/debian/rules
@@ -11,10 +11,12 @@ override_dh_auto_configure:
 
 override_dh_auto_build:
 	./Setup build
+	pod2man --center="User Commands" --section=1 \
+		pandoc-citeproc-preamble.1.pod > pandoc-citeproc-preamble.1
 
 override_dh_auto_clean:
 	if [ -x Setup ]; then ./Setup clean; fi
-	rm -f Setup Setup.o Setup.hi
+	rm -f Setup Setup.o Setup.hi pandoc-citeproc-preamble.1
 
 override_dh_strip:
 	# GHC cannot produce debugging symbols so the -dbgsym package
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)