Pandoc (http://pandoc.org/) is a universal document converter. Taking as input Markdown/Wiki-like syntax, you can obtain an .odt, .docx, .tex, or even Beamer slides (like here)! In this presentation we introduce Pandoc. We then zoom on some interesting technical details (parameters, template language, ability to embed LaTeX into Markdown, ways to rewrite your AST with external bindings, etc.) We believe Pandoc is a very useful piece of software that is worth studying (including for education/research purposes). The slides have been written by Erwan Bousse (http://people.irisa.fr/Erwan.Bousse/) in Pandoc (of course!) and presented in the context of the DiverSE coffee (a weekly meeting of the DiverSE team: http://diverse.irisa.fr).

1. Pandoc — a universal document converter
DiverSE Coffee
Erwan Bousse Mathieu Acher
June 4, 2015
Erwan Bousse, Mathieu Acher Pandoc 1/16

2. Outline
1 Short introduction and demo
2 Pandoc usages
3 Some details of Pandoc
4 Pandoc for education and research?
Erwan Bousse, Mathieu Acher Pandoc 2/16

3. What is pandoc?
From their website: “If you need to convert files from one markup
format into another, pandoc is your swiss-army knife”
Command-line tool that processes a markup format
(markdown, wiki syntax, etc.), and produces a document
(LATEX, epub, docx, etc.)
Written in Haskell in a modular fashion (one module per
input language and per output language)
GPL licensed
Can also be used directly as a Haskell library
Erwan Bousse, Mathieu Acher Pandoc 3/16

4. Input markup formats
“A markup language is a system for annotating a document in a
way that is syntactically distinguishable from the text.”, Wikip´edia
Presentation-neutral:
markdown, reStructuredText, textile, DocBook, MediaWiki
markup, TWiki markup, Haddock markup, OPML, Emacs
Org-Mode, Txt2Tags
Not really presentation neutral:
HTML, LaTeX, Microsoft Word docx, EPUB
Erwan Bousse, Mathieu Acher Pandoc 4/16

5. Output document formats
HTML formats: XHTML, HTML5, and HTML slide shows
using Slidy, reveal.js, Slideous, S5, or DZSlides.
Word processor formats: Microsoft Word docx,
OpenOffice/LibreOffice ODT, OpenDocument XML
Ebooks: EPUB version 2 or 3, FictionBook2
Documentation formats: DocBook, GNU TexInfo, Groff man
pages, Haddock markup
Page layout formats: InDesign ICML
Outline formats: OPML
TeX formats: LaTeX, ConTeXt, LaTeX Beamer slides
PDF via LaTeX
Lightweight markup formats: Markdown (including
CommonMark), reStructuredText, AsciiDoc, MediaWiki
markup, DokuWiki markup, Emacs Org-Mode, Textile
Erwan Bousse, Mathieu Acher Pandoc 5/16

6. Demo: from Markdown to Stuff
Demo o/
Erwan Bousse, Mathieu Acher Pandoc 6/16

7. Pandoc usages
Motivations:
To go from a format to another (if you don’t care about
formatting, since only the content is kept)
To write things once, and to export to multiple formats
To write things in a nice lightweight language (instead of
horrible LATEX, for instance)
. . .
To make:
Slides (like these ones!)
Report
Book
Conference/journal paper? (yet to be tried )
. . .
Erwan Bousse, Mathieu Acher Pandoc 7/16

8. A view of pandoc (official website)
Erwan Bousse, Mathieu Acher Pandoc 8/16

9. Hidden Pivot Metamodel
http://hackage.haskell.org/package/pandoc-types-1.12.
4.2/docs/Text-Pandoc-Definition.html#t:Block
Erwan Bousse, Mathieu Acher Pandoc 9/16

10. Huge amount of options
http://pandoc.org/README.html#general-options
Erwan Bousse, Mathieu Acher Pandoc 10/16

11. Metadata and templates
YAML metadata to parameterize the template of the output
language
Provides an easy way to customize header + footer (very nice
for LATEX output)
Very simple template language to do so: conditionnals and
loops (with separators)
Erwan Bousse, Mathieu Acher Pandoc 11/16

12. Filters
Possibility to define filters to rework the AST (e.g. extend the
input language)
Erwan Bousse, Mathieu Acher Pandoc 12/16

13. Pandoc for education
A “case” for explaining advanced concepts
Software Languages
– parsing
– domain-specific languages, expressiveness, extensibility
– strategies for “growing up” and mixing different languages
(YAML, templating, Python bindings, grammar islands?)
Model-driven Engineering
– pivot metamodel, model transformations
Software Product Lines
– parameters (command line level), input variants, output
variants
– reuse/extensibility mechanisms
Erwan Bousse, Mathieu Acher Pandoc 13/16

14. Pandoc for research
A “case” for investigating SLE, MDE, and SPL problems
Languages: eg how to address language extensibility
problems?
Modeling: eg how to design a pivot metamodel?
Variability: eg how to test/maintain/introduce plenty of
parameters for plenty of inputs and plenty of outputs?
Erwan Bousse, Mathieu Acher Pandoc 14/16

15. Summary
Pandoc: useful tool for writing reports, slides, papers
Pandoc for interns, engineers, researchers, or assistants
Pandoc for educators and scientists (worth studying in details
Pandoc)
Open question: how to study Pandoc and render the
understanding/knowledge?
Erwan Bousse, Mathieu Acher Pandoc 15/16

16. Example: a customised markdown → beamer workflow
Available here:
https://git.framasoft.org/Gwendal/
better-pandoc-markdown2beamer
Makes use of:
A customised beamer output template with more metadata
handling (e.g. insitute) and a style
A filter to extend the input markdown with a new [columns]
syntax to create beamer columns
Erwan Bousse, Mathieu Acher Pandoc 16/16