Pandoc — a universal document converter

DiverSE Coffee

Erwan Bousse Mathieu Acher

June 4, 2015

Erwan Bousse, Mathieu Acher Pandoc 1/16

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

What is pandoc?

From their website: “If you need to convert files from one markupformat 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 perinput language and per output language)

GPL licensed

Can also be used directly as a Haskell library

Erwan Bousse, Mathieu Acher Pandoc 3/16

Input markup formats

“A markup language is a system for annotating a document in away that is syntactically distinguishable from the text.”, Wikipedia

Presentation-neutral:

markdown, reStructuredText, textile, DocBook, MediaWikimarkup, TWiki markup, Haddock markup, OPML, EmacsOrg-Mode, Txt2Tags

Not really presentation neutral:

HTML, LaTeX, Microsoft Word docx, EPUB

Erwan Bousse, Mathieu Acher Pandoc 4/16

Output document formats

HTML formats: XHTML, HTML5, and HTML slide showsusing 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 manpages, Haddock markup

Page layout formats: InDesign ICML

Outline formats: OPML

TeX formats: LaTeX, ConTeXt, LaTeX Beamer slides

PDF via LaTeX

Lightweight markup formats: Markdown (includingCommonMark), reStructuredText, AsciiDoc, MediaWikimarkup, DokuWiki markup, Emacs Org-Mode, Textile

Erwan Bousse, Mathieu Acher Pandoc 5/16

Demo: from Markdown to Stuff

Demo \o/

Erwan Bousse, Mathieu Acher Pandoc 6/16

Pandoc usages

Motivations:

To go from a format to another (if you don’t care aboutformatting, 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 ofhorrible 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

A view of pandoc (official website)

Erwan Bousse, Mathieu Acher Pandoc 8/16

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

Huge amount of options

http://pandoc.org/README.html#general-options

Erwan Bousse, Mathieu Acher Pandoc 10/16

Metadata and templates

YAML metadata to parameterize the template of the outputlanguage

Provides an easy way to customize header + footer (very nicefor LATEX output)

Very simple template language to do so: conditionnals andloops (with separators)

Erwan Bousse, Mathieu Acher Pandoc 11/16

Filters

Possibility to define filters to rework the AST (e.g. extend theinput language)

Erwan Bousse, Mathieu Acher Pandoc 12/16

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, outputvariants

– reuse/extensibility mechanisms

Erwan Bousse, Mathieu Acher Pandoc 13/16

Pandoc for research

A “case” for investigating SLE, MDE, and SPL problems

Languages: eg how to address language extensibilityproblems?

Modeling: eg how to design a pivot metamodel?

Variability: eg how to test/maintain/introduce plenty ofparameters for plenty of inputs and plenty of outputs?

Erwan Bousse, Mathieu Acher Pandoc 14/16

Summary

Pandoc: useful tool for writing reports, slides, papers

Pandoc for interns, engineers, researchers, or assistants

Pandoc for educators and scientists (worth studying in detailsPandoc)

Open question: how to study Pandoc and render theunderstanding/knowledge?

Erwan Bousse, Mathieu Acher Pandoc 15/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 metadatahandling (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