--- title: pandoc papers subtitle: a future proof way to write author: - Christian Krause ... intro ===== ## motivation #1  ## motivation #2 - **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 - 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 ### target**s** - 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](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 ### [set up new project in GitLab](https://git.idiv.de/projects/new) - 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 ### 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 ### continuous deployment - some parts are done automatically with the project template - deploy PDF to cloud storage: [https://portal.idiv.de/nextcloud/](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](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/) ### 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](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