From d66301d8aca7be2821a083dd7cbefb20bdf164ad Mon Sep 17 00:00:00 2001 From: Sean Whitton Date: Sat, 4 Feb 2017 13:23:28 -0700 Subject: add manpage --- debian/changelog | 3 +- debian/manpages | 1 + debian/rules | 4 ++- pandoc-citeproc-preamble.1.pod | 76 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 82 insertions(+), 2 deletions(-) create mode 100644 debian/manpages create mode 100644 pandoc-citeproc-preamble.1.pod 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 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 + +=head1 DESCRIPTION + +B 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 + +Default citeproc preamble for Pandoc output format I +(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 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 + +=head1 SEE ALSO + +pandoc(1), pandoc-citeproc(1) -- cgit v1.2.3