paper.md

% 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

- **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 (closed)

• 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 (closed)

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 (closed)

write paper in Markdown

workflow #2 (closed)

discussion / reviews

• issues
• merge requests
• commit comments

invite collaborators: send link to GitLab

workflow #3 (closed)

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

# 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