Merge branch '40-refine-pandoc-build-workflow-using-build-script' into 'master'

Resolve "Refine pandoc build workflow using build script"

Closes #40

See merge request fastexitlane/latex-boilerplate!22

.gitignore

@@ -6,12 +6,14 @@ temp/
 ## main build output
 main.pdf
 chapter/out.tex
+chapter/out.md
 
 ## IDE and Editor files
 .idea/**
 *.iml
 .sublime-project
 .sublime-workspace
+.vscode/tasks.json
 
 ## MS Office Temp Files
 ~$*.ppt*

.vscode/tasks.json

@@ -1,33 +0,0 @@
-{
-    // See https://go.microsoft.com/fwlink/?LinkId=733558
-    // for the documentation about the tasks.json format
-    "version": "2.0.0",
-    "tasks": [
-        {
-            "label": "latexmk",
-            "type": "shell",
-            "command": "latexmk -latexoption=\"-shell-escape\" main.tex",
-            "group": {
-                "kind": "build",
-                "isDefault": true
-            },
-            "dependsOrder": "sequence",
-            "dependsOn": ["clean"]
-        },
-        {
-            "label": "clean",
-            "type": "shell",
-            "command": "latexmk -C; if [ -f chapter/out.tex ]; then rm chapter/out.tex; fi"
-        },
-        {
-            "label": "pandoc",
-            "type": "shell",
-            "command": [
-                "pandoc --filter pandoc-crossref --filter pandoc-citeproc ",
-                "-M cref=true --top-level-division=chapter ",
-                "--bibliography library/library.bib --biblatex ",
-                "-o chapter/out.tex chapter/*.md"
-            ]
-        }
-    ]
-}

README.md

@@ -25,14 +25,20 @@ git pull boilerplate master
 git remote remove boilerplate
 ```
 
-In order to use the preconfigured CI / CD pipeline for building PDFs, copy either `latex.gitlab-ci.yml` or `markdown.gitlab-ci.yml` to `.gitlab-ci`, depending on which workflow you want to use.
-On GitLab.com, this will use Dockerized builds by default.
-If you want to use the workflow on own hardware, make sure your GitLab CI meets the [Basic Requirements](https://gitlab.com/fastexitlane/latex-boilerplate/wikis/GitLab-CI#basic-requirements).
+In order to setup the repo for CI / CD on GitLab and Azurre DevOps, as well as VS Code integration, run `setup.sh latex` or `setup.sh markdown`, depending in which workflow you want to use.
+CI will use Dockerized builds by default.
+If you want to use the workflow on GitLab, but with own hardware, make sure your GitLab CI meets the [Basic Requirements](https://gitlab.com/fastexitlane/latex-boilerplate/wikis/GitLab-CI#basic-requirements).
 
 If you know what you're doing, simply start adding your content files in `chapter/` as LaTex `\chapter`s and `\input` them into `main.tex`.
+You can then run the build using VS Code preconfigured tasks or using `build.sh`. 
+
+For Markdown, add your content as `*.md` files in `chapter/` and prefix them with ascending numbers (to keep chapter sequence).
+You shouldn't need to `\input` or configure anything else, as the files are concatenated automatically at build time.
+Run `build.sh pandoc` to build your PDF.
+
 If you do not know what you're doing or get into trouble - or want to use the **Markdown Workflow**, you may want to consider the [wiki](https://gitlab.com/fastexitlane/latex-boilerplate/wikis/home) ;-)
 
 
 ## Docker Images
 If you need a Docker image to build your documents, head over to [pandoc-latex](https://github.com/fastexitlane/pandoc-latex) ([DockerHub](https://hub.docker.com/r/fastexitlane/pandoc-latex)).
-Also, there's a prebuilt Docker image for spellchecking using Hunspell - head over to [docker-hunspell](https://github.com/fastexitlane/docker-hunspell).
+Also, there's a prebuilt Docker image for spellchecking using Hunspell - head over to [docker-hunspell](https://github.com/fastexitlane/docker-hunspell).

build.sh

@@ -0,0 +1,25 @@
+#!/bin/bash
+
+# cleanup
+latexmk -C
+if [ -f chapter/out.tex ]
+then
+    rm chapter/out.md
+    rm chapter/out.tex
+fi
+
+# run pandoc
+if [ $1 == "pandoc"]
+then
+    cat chapter/*.md > chapter/out.md
+    pandoc --filter pandoc-citeproc --filter pandoc-crossref \
+        -M cref=true --top-level-division=chapter \
+        --bibliography library/library.bib --biblatex \
+        -o chapter/out.tex chapter/out.md
+fi
+
+# run latex build
+if [ $1 != "clean" ]
+then
+    latexmk -latexoption="-shell-escape" main.tex
+fi

config.tex

@@ -201,3 +201,7 @@
 
 % Verbessert das Referenzieren von Kapiteln, Abbildungen etc.
 \usepackage[german,capitalise]{cleveref}
+
+% Pandoc Integration
+\providecommand{\tightlist}{%
+  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

setup.sh

@@ -0,0 +1,28 @@
+#!/bin/bash
+
+function write_help {
+    echo "Usage:"
+    echo "    ./setup.sh markdown    Setup Boilerplate for usage with Markdown"
+    echo "    ./setup.sh latex       Setup Boilerplate for usage with LaTex"
+}
+
+if [ $# == 0 ]
+then
+    write_help
+    exit 1
+fi
+    
+if [ $1 == "markdown" ]
+then
+    cp templates/markdown.gitlab-ci.yml ./.gitlab-ci.yml
+    cp templates/markdown.azure-pipelines.yml ./azure-pipelines.yml
+    cp templates/markdown.tasks.json ./.vscode/tasks.json
+    cp templates/markdown.main.tex ./main.tex
+elif [ $1 == "latex" ]
+then
+    cp templates/latex.gitlab-ci.yml ./.gitlab-ci.yml
+    cp templates/latex.azure-pipelines.yml ./azure-pipelines.yml
+    cp templates/latex.tasks.json ./.vscode/tasks.json
+else
+    write_help
+fi

templates/latex.azure-pipelines.yml

@@ -23,8 +23,8 @@ stages:
     - job: latexmk
       container: fastexitlane/pandoc-latex:latest
       steps:
-      - script: latexmk main.tex
-        displayName: Execute LaTex Build
+      - script: ./build.sh
+        displayName: Run Build Script
       - task: PublishBuildArtifacts@1
         inputs:
           ArtifactName: main.pdf

templates/latex.gitlab-ci.yml

@@ -10,7 +10,7 @@ latexmk:
       - main*.pdf
     expire_in: 2d
   script:
-    - latexmk main.tex
+    - ./build.sh
     - ci_commit_sha_short=`git rev-parse --short $CI_COMMIT_SHA`
     - mv main.pdf main@$ci_commit_sha_short.pdf
 

templates/latex.tasks.json

@@ -0,0 +1,24 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "latexmk",
+            "type": "shell",
+            "command": "${workspaceFolder}/build.sh",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "dependsOrder": "sequence",
+            "dependsOn": ["clean"]
+        },
+        {
+            "label": "clean",
+            "type": "shell",
+            "command": "${workspaceFolder}/build.sh clean",
+            "group": "none",
+        }
+    ]
+}

templates/markdown.azure-pipelines.yml

@@ -22,10 +22,8 @@ stages:
     jobs:
     - job: pandoc_latexmk
       steps:
-        - script: pandoc --filter pandoc-crossref --filter pandoc-citeproc -M cref=true --top-level-division=chapter --bibliography library/library.bib --biblatex -o chapter/out.tex chapter/*.md
-          displayName: Convert Markdown Files to LaTex
-        - script: latexmk main.tex
-          displayName: Execute LaTex Build
+        - script: ./build.sh pandoc
+          displayName: Run Build Script with Pandoc Option
         - task: PublishBuildArtifacts@1
           inputs:
             ArtifactName: main.pdf

templates/markdown.gitlab-ci.yml

@@ -11,8 +11,7 @@ pandoc_latexmk:
       - main*.pdf
     expire_in: 2d
   script:
-    - pandoc --filter pandoc-crossref --filter pandoc-citeproc -M cref=true --top-level-division=chapter --bibliography library/library.bib --biblatex -o chapter/out.tex chapter/*.md
-    - latexmk main.tex
+    - ./build.sh pandoc
     - ci_commit_sha_short=`git rev-parse --short $CI_COMMIT_SHA`
     - mv main.pdf main@$ci_commit_sha_short.pdf
 

templates/markdown.main.tex

@@ -0,0 +1,80 @@
+% Makros
+\newcommand{\dokumententyp}{Dokumententyp}
+\newcommand{\abgabedatum}{\today} 
+\newcommand{\ort}{Ort} 
+\newcommand{\dokumententitel}{Titel}
+\newcommand{\dokumentenuntertitel}{Untertitel}
+\newcommand{\dokumentenautor}{Autor}
+\newcommand{\matrikelnr}{Matrikel-Nr.}
+\newcommand{\dokumentenautoradresse}{Adresse}
+\newcommand{\dokumentenpruefer}{Prüfer}
+\newcommand{\studiengang}{Studiengang}
+\newcommand{\studiengruppe}{Studiengruppe}
+\newcommand{\institution}{Institution}
+
+% config
+\input{config.tex}
+
+\begin{document}
+  %%%%%%%%%%%%%%%%%%%%%%%%%
+  %% document title page %%
+  %%%%%%%%%%%%%%%%%%%%%%%%%
+  \input{additionals/title.tex}
+
+  %%%%%%%%%%%%%
+  %% indexes %%
+  %%%%%%%%%%%%%
+  \pagenumbering{Roman}
+
+  % disclosure statement - uncomment if needed
+  % \input{additionals/disclosure.tex}
+  % \newpage
+
+  % executive summary - uncomment if needed
+  % \input{additionals/executive_summary.tex}
+  % \newpage
+
+  % table of contents
+  \tableofcontents
+  \newpage
+
+  % acronyms
+  \input{additionals/acronyms.tex}
+  \newpage
+
+  % list of figures
+  \listoffigures
+  \newpage
+
+  % list of tables
+  \listoftables
+  \newpage
+
+  % list of listings
+  \listoflistings
+  \newpage
+
+  %%%%%%%%%%%%%
+  %% content %%
+  %%%%%%%%%%%%%
+  \pagenumbering{arabic}
+
+  % when using pandoc workflow, we only need to include the build output
+  \input{chapter/out.tex}
+  \newpage
+
+  %%%%%%%%%%%%%
+  %% closing %%
+  %%%%%%%%%%%%%
+  % list of references
+  \input{additionals/references.tex}
+  \newpage
+
+  % appendix - uncomment if needed
+  % \input{appendix/appendix.tex}
+  % \newpage
+
+  % affirmation
+  \input{additionals/affirmation.tex}
+
+\end{document}

templates/markdown.tasks.json

@@ -0,0 +1,24 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "latexmk",
+            "type": "shell",
+            "command": "${workspaceFolder}/build.sh pandoc",
+            "group": {
+                "kind": "build",
+                "isDefault": true
+            },
+            "dependsOrder": "sequence",
+            "dependsOn": ["clean"]
+        },
+        {
+            "label": "clean",
+            "type": "shell",
+            "command": "${workspaceFolder}/build.sh clean",
+            "group": "none",
+        }
+    ]
+}