pandoc-papers.md

title: pandoc papers
subtitle: a future proof way to write
author:
- Christian Krause

intro

motivation #1 (closed)

motivation #2 (closed)

• focus on content/writing
• communication
  • avoid emails with attachments, right?
  • early and frequent reviews
• get rid of MS Word, Google Docs, Dropbox, etc.

motivation #3 (closed)

• use version control with all its benefits
• automated
  • spell checking
  • high quality typesetting
  • publishing
• future proof way of doing things, meaning
  • tools are open source
  • tools are replaceable or optional
  • all content is plain text

agenda

• short presentation including demo
• learn tools and workflows
• establish community

tools

pandoc -- Swiss Army Knife of Text Conversion

source: markup

• usually Markdown
• less powerful than \LaTeX, but inline \LaTeX\ can be used

targets

• high quality PDF via \LaTeX
• others: HTML web page, EPUB, Office documents

templates

• different journals
• iDiv branding

Markdown

source

- **easy to learn**, read and write
- ~~no~~ fewer distractions to *procrastinate*
- inline \LaTeX\ if needed \rightarrow\ $a^2 + b^2 = c^2$

rendered

• easy to learn, read and write
• no fewer distractions to procrastinate
• inline \LaTeX\ if needed \rightarrow\ a^2 + b^2 = c^2

git & GitLab

git

• version control
• free backup

GitLab: https://git.idiv.de

• self-hosted, full access control
• communication: discussion and reviews
• continuous integration i.e. spell checking
• continuous deployment to e.g. cloud storage

visualization

Graphviz/dot

• graph visualization language
• define flowcharts with code
• dot handles rendering to SVG

plotting

• any programming language can be used
• add results as CSV to repository
• plot data to SVG e.g. using R with ggplot2 and svglite

build tool

make

• glues everything together
• automates build
  • render images from dot and CSV sources
  • build PDF
  • run spell check

workflow

workflow #1 (closed)

set up new project in GitLab

• use project template
• template is managed by our community
• contains Makefile, README, CI/CD, themes, visualization examples, etc.

writing

• start writing the main document in Markdown
• use text editor you're comfortable with

workflow #2 (closed)

communication

• invite contributors / collaborators to GitLab project
• use GitLab project as main communication platform
• discuss and review in
  • commit comments
  • issues
  • merge requests

workflow #3 (closed)

continuous deployment

• some parts are done automatically with the project template
• deploy PDF to cloud storage: https://portal.idiv.de/nextcloud/
• (uses DRAFT watermark if commit not tagged)

demo

(demo here only if all tools are already installed)