Code owners
Assign users and groups as approvers for specific file changes. Learn more.
- intro
- motivation #1 (closed)
- motivation #2 (closed)
- motivation #3 (closed)
- agenda
- tools
- pandoc -- Swiss Army Knife of Text Conversion
- source: markup
- targets
- templates
- Markdown
- source
- rendered
- git & GitLab
- git
- GitLab: https://git.idiv.de
- visualization
- Graphviz/dot
- plotting
- build tool
- make
- workflow
- workflow #1 (closed)
- set up new project in GitLab
- writing
- workflow #2 (closed)
- communication
- workflow #3 (closed)
- continuous deployment
- demo
- your turn
- discussion
- let's get started
- create new project
- editor: Atom
- issues
- prose diff tool
- spell checking
- community
- contributing
- https://git.idiv.de/publishing
pandoc-papers.md 4.71 KiB
title: pandoc papers
subtitle: a future proof way to write
author:
- Christian Krause
intro
#1 (closed)
motivation#2 (closed)
motivation- focus on content/writing
-
communication
- avoid emails with attachments, right?
- early and frequent reviews
- get rid of MS Word, Google Docs, Dropbox, etc.
#3 (closed)
motivation- 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
-
nofewer distractions to procrastinate - inline \LaTeX\ if needed \rightarrow\ a^2 + b^2 = c^2
git & GitLab
git
- version control
- free backup
https://git.idiv.de
GitLab:- 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
#1 (closed)
workflowset 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
#2 (closed)
workflowcommunication
- invite contributors / collaborators to GitLab project
- use GitLab project as main communication platform
- discuss and review in
- commit comments
- issues
- merge requests
#3 (closed)
workflowcontinuous 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