From 587dd51b859e030bae6e34aaaae78e5373e8a459 Mon Sep 17 00:00:00 2001 From: Christian Krause <christian.krause@idiv.de> Date: Tue, 7 May 2019 14:13:13 +0200 Subject: [PATCH] updates pandoc papers --- .gitignore | 1 + Makefile | 12 +-- pandoc-papers.md | 191 +++++++++++++++++++++++++++++++++++++++++++++++ paper.md | 157 -------------------------------------- 4 files changed, 199 insertions(+), 162 deletions(-) create mode 100644 pandoc-papers.md delete mode 100644 paper.md diff --git a/.gitignore b/.gitignore index 454712c..7eb5a5d 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,4 @@ img/git-remote-solo.svg img/license-chooser.svg img/motivation-throwaway-playground.svg img/staging-area.svg +*.pdf diff --git a/Makefile b/Makefile index 074282d..0cc1690 100644 --- a/Makefile +++ b/Makefile @@ -4,11 +4,13 @@ SUBDIRS = \ $(SUBDIRS): $(MAKE) -C $@ -paper.html: paper.md - pandoc -t revealjs -s paper.md -o paper.html - -paper.pdf: paper.md - pandoc -s paper.md -o paper.pdf +pandoc-papers.pdf: paper.md + pandoc \ + -V aspectratio=169 \ + -V institute=iDiv \ + -V theme=Frankfurt \ + -V navigation=horizontal \ + -s paper.md -t beamer -o pandoc-papers.pdf all: subdirs diff --git a/pandoc-papers.md b/pandoc-papers.md new file mode 100644 index 0000000..72f575f --- /dev/null +++ b/pandoc-papers.md @@ -0,0 +1,191 @@ +% 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 + +# 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, epub, docx, odt + +### templates + +- different journals +- iDiv branding +- draft branding + +## Markdown + +### rendered + +- **easy to learn**, read and write +- no distractions to *procrastinate* +- inline LaTeX if needed: $a^2 + b^2 = c^2$ + +### source + +``` +- **easy to learn**, read and write +- no distractions to *procrastinate* +- inline LaTeX if needed: $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 +- use **make** to build + +### R scripts + +- add results as CSV to repository +- visualize data in CSV to charts +- use **make** to build + +## make + +### simple build tool + +- glues everything together +- automated build + - render images from **dot** and **CSV** sources + - build PDF + +# 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 good 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 + +# misc + +## 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 #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 +- `.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 + +# your turn + +## discussion + +- Which tools do you currently use? +- What are your workflows? +- How do you communicate, collaborate and review? +- What annoys you the most? (i.e. how can we improve) + +## let's use it + +- install tools +- install editor +- set up git project +- convert existing documents to Markdown +- build with pandoc diff --git a/paper.md b/paper.md deleted file mode 100644 index dc43c94..0000000 --- a/paper.md +++ /dev/null @@ -1,157 +0,0 @@ -% 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$ - -```markdown -- **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 - -- 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 -### 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 - -write paper in Markdown - -## workflow #2 -### discussion / reviews - -- issues -- merge requests -- commit comments - -invite collaborators: send link to GitLab - -## workflow #3 -### 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 - -```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 -``` - -## 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 -- GitLab