% pandoc papers workshop
% Christian Krause

# intro

## goals

- **focus** on content/writing
- use **version control** with all its benefits
- next generation **communication**
  - avoid emails with attachments, right?
  - early and frequent reviews improve quality
- **automated** publishing
  - high quality typesetting
- get rid of MS Word, Google Docs, Dropbox

# 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, epub, docx, odt

### templates

- different journals
- iDiv branding
- draft branding

## Markdown

### rendered

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

### source

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

## make

### simple build tool

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

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

# your turn

## discussion

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

## let's use it

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