pandoc-papers.md

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

intro

motivation #1 (closed)

motivation #2 (closed)

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

• 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

targets

• 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

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

set up new project in GitLab

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

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

continuous deployment

• some parts are done automatically with the project template
• deploy PDF to cloud storage: 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, gitlab-ce#26804
• 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

• 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