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

intro
=====

## motivation #1

![](img/motivation-draft-mess-half-size.png)

## motivation #2

- **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

- 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

### target**s**

- 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](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

### [set up new project in GitLab](https://git.idiv.de/projects/new)

- 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

### 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

### continuous deployment

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

## demo

(demo here only if all tools are already installed)


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)

## let's get started

### create new project

- https://git.idiv.de/projects/new
- **create from template** \rightarrow\ **instance** \rightarrow\ **pandoc**
- install tools from `README.md`
- set up Nextcloud share and CD

### editor: Atom

- **atom-latex** for bib syntax highlighting
- **graphviz-preview-plus** for dot syntax highlighting and preview
- **hard-wrap** for wrapping paragraphs
- **language-pfm** for pandoc flavored Markdown
- **language-r** for R

## issues

### prose diff tool

- hard wrap vs soft wrap
- 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/)

### spell checking

- integrate editor spell checking with **mdspell**
- per project editor integration
- needs additional ignores, e.g. links, \LaTeX\ and citations


community
=========

## contributing

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

- contribute to **project template** about build / workflow related issues
  - e.g. if you need more packages for plotting
- contribute to **bibliography** about new references
  - we may even import/sync an existing publication database
- contribute to **pandoc templates**
  - had no need for them yet
  - we might add some iDiv corporate identity (talk with PR)
  - **review-able** template with link to join discussion at every paragraph