% pandoc papers
% Christian Krause

# intro

## goals

- focus on content/writing
- version control
- next generation communication
  - avoid emails with attachments, right?
  - reviews!
- automated publishing
  - high quality typesetting

# tool overview

## markdown

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

```markdown
- **easy to learn**, read and write
- no distractions to *procrastinate*
- no fiddling with `WYSIWYG`
- inline LaTeX if needed: $a^2 + b^2 = c^2$
```

## git

- version control
- free backup
- easy revert

## GitLab

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

## pandoc #1

- render markup source ...
  - usually **Markdown**
  - markup less powerful than LaTeX
  - but inline LaTeX can be used
- ... to high quality target
  - PDF via LaTeX

## pandoc #2
### supports templates

- different journals
- iDiv branding
- draft branding

## make

- automate build
- use visualization tools

# optional tools

## Graphviz/dot

- graph visualization language
- define flowcharts with code
- **dot** handles rendering
- use **make** to build

## R scripts

- CSV2charts
- use **make** to build

# branching model

## multi master

- paper with many journals, different paper text
- one branch per journal
- carefully **cherry-pick** additions to all masters

## trunk based development

- same paper text
- different themes for journals
- journal-themes via sub-module
  - make themes reusable

# workflow

## workflow #1

write paper in Markdown

## workflow #2
### discussion / reviews

- issues
- merge requests
- commit comments

invite collaborators: send link to GitLab

## workflow #3
### continuous deployment

- deploy PDF to cloud storage
- draft watermark template if commit not tagged
- send others link to PDF in cloud storage

## workflow #4
### templates

- write templates across teams
- use git sub-modules to include
- share with all@idiv / world

# misc

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

## unsolved problems

- to wrap or not to wrap
- true paragraph-based diff
- we don't have solid CD yet
- can CD deploy to nextcloud share?
- review-able PDF template
  - link to join discussion at every paragraph

# your turn

## discussion

- what do you use today?
- what annoys you the most?

## let's use it

- install tools
- set up git project
- convert existing stuff to markdown
- build with pandoc

# EOF