pdoc - typeset pandoc documents with document-specific, default options
version 0.900
This is just a small executable and a hack to pandoc: you can use it to set document-specific, default options for pandoc in the typesetting process. Of course, you can safely ignore these settings and return to the standard way of doing things at all times.
Usage is absolutely straight-forward:
If you want your file to be typeset using the document-specific default options, run
pdoc file.pandoc
If you want standard processing of that file, simply run pandoc as usual:
pandoc file.pandoc
Sprinkle <!--+ --pandoc-option1 --pandoc--option2 +--> all over your pandoc file -- just as your would use them on the shell. pdoc will read these and add them to the commandline that is passed to a standard pandoc typesetting.
<!--+ --pandoc-option1 --pandoc--option2 +-->
pdoc
Use <!--& (some post processing action) &--> as the special markup to pdoc for post-processing options. These will be concatenated to the pandoc-commandline that is generated via &&, just like so:
<!--& (some post processing action) &-->
&&
% pandoc --option1 --option2 && your-command-1 && your-command2
This is just a simple hack reading out specially marked comments in your pandoc source. Everything will stay usable as always. When typesetting in the standard manner, these comments are simply ignored.
See the executable for the details.
You can use shell variables as usual, e.g. $HOME, etc.
$HOME
When doing more complicatd things (see example below) I like to use so-called pandoc-policies (as I call them).
I keep a folder ~/.pandoc/policies next to ~/.pandoc/templates containing files like ~/.pandoc/policies/columns.latex (handling column-layouts) ~/.pandoc/policies/squeeze.latex (for whitespace squeezing), and so on...
~/.pandoc/policies
~/.pandoc/templates
~/.pandoc/policies/columns.latex
~/.pandoc/policies/squeeze.latex
All of these policies are to be included by pandoc's -H / --include-in-header=-switch, so it makes:
pandoc
-H / --include-in-header=
% pandoc -H $HOME/.pandoc/policies/squeeze.latex -o document.{pdf,pandoc}
Suppose you have a squeeze and a columns-policy in your policy-folder, your document might look like this:
% John Doe % Interesting topic % 01/01/2013 <!--+ --include-in-header=$HOME/.pandoc/policies/squeeze.latex --include-in-header=$HOME/.pandoc/policies/columns.latex +--> # Regular pandoc/markdown Heading 1 * A list * of things * etc.
Here is a somewhat more complicated example: the cheat-sheet generator that I'm currently using while learning for my final examination:
% Parsing -- Summary % Daniel B. % Oct/Nov 2012 <!-- Default options --> <!-- =============== --> <!--+ -H $HOME/.pandoc/templates/policies/{squeeze,columns}.latex +--> <!--+ -sSN --toc +--> <!--+ -Vfontsize:8pt,a4paper,twocolumn,landscape +--> <!--+ -o parsing.pdf +--> <!-- Unused options (regular comments) --> <!-- ================================= --> <!-- -H $HOME/.pandoc/templates/policies/columns.latex +--> <!-- -H $HOME/.pandoc/templates/policies/chapterstyle.latex +--> <!-- -H $HOME/.pandoc/templates/policies/numbering.latex +--> <!-- Post-typeset exec --> <!-- ================= --> <!--& pdfnup --nup 1x2 --no-landscape parsing.pdf --outfile parsing.pdf &--> <!--& open parsing.pdf &--> ------------------------------------------------------------------------------ # Part I: Basics ## Chapter 1: What exactly is Parsing? Text goes here....
This cheat-sheet generator can simply be called using pdoc cheatsheet.pandoc and will additionally use pdfjam to squeeze even more of the resulting pdf pages together. On a Mac, it will additionally open the file after the final pdfjam rendering for quality inspection ;-).
pdoc cheatsheet.pandoc
Note how several policies are grouped together on shell level, using curly-bracket expansion:
-H $HOME/.pandoc/templates/policies/{squeeze,columns}.latex
Also note, how additional options are set via pandoc's -V-switch, and how even more options are smuggled in into pandoc's own latex template. (The latter you can find using pandoc -D latex) in using
-V
pandoc -D latex
-Vfontsize:8pt,a4paper,twocolumn,landscape
pandoc: http://johnmacfarlane.net/pandoc/
pdfjam: http://go.warwick.ac.uk/pdfjam
DBR <dbr@cpan.org>
This software is Copyright (c) 2012 by DBR.
This is free software, licensed under:
DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE, Version 2, December 2004
To install pdoc, copy and paste the appropriate command in to your terminal.
cpanm
cpanm pdoc
CPAN shell
perl -MCPAN -e shell install pdoc
For more information on module installation, please visit the detailed CPAN module installation guide.