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

# intro

## motivation

- **focus** on content/writing
- use **version control** with all its benefits
- **communication**
  - avoid emails with attachments, right?
  - early and frequent reviews
- **automated**
  - spell checking
  - high quality typesetting
  - publishing
- get rid of MS Word, Google Docs, Dropbox
- **future proof** way of doing things

## agenda

- short presentation
- demo
- tool installation
- your first project
- learn tools and workflows
- establish community

# tools

## pandoc

### source: markup

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

### target**s**

- high quality PDF via \LaTeX
- others: html web page, epub, docx, odt

### templates

- different journals
- iDiv branding
- draft branding

## Markdown

### source

```
- **easy to learn**, read and write
- no distractions to *procrastinate*
- inline \LaTeX\ if needed, e.g. $a^2 + b^2 = c^2$
```

### rendered

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

## git & GitLab

### git

- version control
- free backup

### GitLab: [https://git.idiv.de](https://git.idiv.de)

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

## visualization

### Graphviz/dot

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

### R scripts

- add results as CSV to repository
- visualize data in CSV to charts

## build tool

### make

- glues everything together
- automated build
  - render images from **dot** and **CSV** sources
  - build PDF
  - run spell check

# workflow

## workflow #1

### project

- set up project in GitLab
  - use **pandoc papers** project template
  - project template is managed by our community
  - contains Makefile, README, themes, CD, etc.
- add contributors / collaborators

### writing

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

## workflow #2

### communication

- use GitLab project as main communication platform
- discuss and review in
  - commit comments
  - issues
  - merge requests
- invite collaborators: send link to GitLab project

## workflow #3

### continuous deployment

- deploy PDF to cloud storage:
  [https://portal.idiv.de/nextcloud/](https://portal.idiv.de/nextcloud/)
- use template with **DRAFT** watermark if commit not tagged

### templates

- manage templates in our community
- keep in separate git repository
- use git sub-module to include
- share with all@idiv / world

# community

## community #1

### pandoc paper project template

- `README.md` with instructions how to build
- `Makefile` with general build instructions
- include pandoc \LaTeX\ themes via sub-module
- CD pipeline instructions
- `main.md` with hello world document using includes for chapters
- example **dot** file for flowchart
- example **CSV** and **R script** to generate charts
- example **BibTeX** integration
- `.gitignore` with default products

## community #2

### prose diff tool

- these issues might help:
  [gitlab-ce#25650](https://gitlab.com/gitlab-org/gitlab-ce/issues/25650),
  [gitlab-ce#26804](https://gitlab.com/gitlab-org/gitlab-ce/issues/26804)
- [https://github.blog/2014-02-14-rendered-prose-diffs/](https://github.blog/2014-02-14-rendered-prose-diffs/)

### continuous deployment

- we don't have solid CD yet
- can CD deploy to Nextcloud share?

### others

- repository with \LaTeX\ templates for pandoc
- **review-able** PDF template with link to join discussion at every paragraph

## community #3

### helpful commands

```bash
# better diff command for text
git diff -w --ignore-blank-lines --word-diff

# watch source and build if changes
watchexec -w paper.md -- make paper.pdf
```

## community #4

### [https://git.idiv.de/publishing](https://git.idiv.de/publishing)

- contribute to project template
- contribute to pandoc templates
- contribute to bibliography

# demo

# your turn

## discussion

- Which tools do you currently use?
  - Anyone know **pandoc-scholar**?
  - Anyone know **authorea**?
- What are your workflows?
- How do you communicate, collaborate and review?
- What annoys you the most? (i.e. how can we improve)

## installation

### tools

- git
- pandoc, pandoc-citeproc
- \LaTeX
- make
- [watchexec](https://github.com/watchexec/watchexec/releases)
- xspell
- graphviz
- R

### editor

- Atom

## workflow

- set up git project
- convert existing documents to Markdown
- build with pandoc