--- title: pandoc papers subtitle: a future proof way to write author: - Christian Krause ... # intro ## motivation - **focus** on content/writing - use **version control** with all its benefits - **communication** - avoid emails with attachments, right? - early and frequent reviews - **automated** - spell checking - high quality typesetting - publishing - get rid of MS Word, Google Docs, Dropbox - **future proof** way of doing things ## agenda - short presentation - demo - tool installation - your first project - learn tools and workflows - establish community # 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 web page, epub, docx, odt ### templates - different journals - iDiv branding - draft branding ## Markdown ### source ``` - **easy to learn**, read and write - no distractions to *procrastinate* - inline \LaTeX\ if needed, e.g. $a^2 + b^2 = c^2$ ``` ### rendered - **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 ## build tool ### make - glues everything together - automated build - render images from **dot** and **CSV** sources - build PDF - run spell check # 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 ``` ## community #4 ### [https://git.idiv.de/publishing](https://git.idiv.de/publishing) - contribute to project template - contribute to pandoc templates - contribute to bibliography # demo # 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) ## installation ### tools - git - pandoc, pandoc-citeproc - \LaTeX - make - [watchexec](https://github.com/watchexec/watchexec/releases) - xspell - graphviz - R ### editor - Atom ## workflow - set up git project - convert existing documents to Markdown - build with pandoc