diff --git a/pandoc-papers.md b/pandoc-papers.md index c8007c4d710a67500752e74e221cab855fceb26a..e475da3da473880b0d1c6075eff0c493766ef5f3 100644 --- a/pandoc-papers.md +++ b/pandoc-papers.md @@ -19,14 +19,15 @@ intro - spell checking - high quality typesetting - publishing -- get rid of MS Word, Google Docs, Dropbox -- **future proof** way of doing things +- get rid of MS Word, Google Docs, Dropbox, etc. +- **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 -- tool installation -- your first project - learn tools and workflows - establish community @@ -44,13 +45,12 @@ tools ### target**s** - high quality PDF via \LaTeX -- others: html web page, epub, docx, odt +- others: HTML web page, EPUB, Office documents ### templates - different journals - iDiv branding -- draft branding ## Markdown @@ -79,6 +79,7 @@ tools - self-hosted, full access control - communication: discussion and reviews +- continuous integration i.e. spell checking - continuous deployment to e.g. cloud storage ## visualization @@ -89,10 +90,11 @@ tools - define flowcharts with code - **dot** handles rendering to **SVG** -### R scripts +### plotting -- add results as CSV to repository -- visualize data in CSV to charts +- 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 @@ -112,9 +114,9 @@ workflow ### [set up new project in GitLab](https://git.idiv.de/projects/new) -- use **pandoc papers** project template +- use **publishing/project-template** as project template - project template is managed by our community -- contains Makefile, README, themes, CD, etc. +- contains Makefile, README, themes, CI/CD, visualization examples etc. ### writing @@ -139,111 +141,72 @@ workflow - 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 +- (uses **DRAFT** watermark if commit not tagged) ## demo (demo here only if all tools are already installed) -community +your turn ========= -## community #1 +## discussion -### pandoc paper project template +- 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) -- `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 +## let's get started -## community #2 +### create new project -### templates +- https://git.idiv.de/projects/new +- **create from template** +- **publishing/project-template** +- install tools from `README.md` +- set up Nextcloud share and CD -- manage templates in our community -- keep in separate git repository -- use git sub-module to include -- share with all@idiv / world +### editor: Atom -## community #3 +- **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/) -### 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 +### spell checking -## community #4 +- integrate editor spell checking with **mdspell** +- per project editor integration +- needs additional ignores, e.g. links, \LaTeX\ and citations -### 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 #5 - -### [https://git.idiv.de/publishing](https://git.idiv.de/publishing) - -- contribute to project template -- contribute to pandoc templates -- contribute to bibliography - - -your turn +community ========= -## discussion +## contributing -- 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 -- for Windows: use [chocolatey](https://chocolatey.org/install) - -### editor - -- Atom - -## workflow +### [https://git.idiv.de/publishing](https://git.idiv.de/publishing) -- set up git project -- convert existing documents to Markdown -- build with pandoc +- 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