From e1f403f1e750a7a825580e81600a53ad425c7484 Mon Sep 17 00:00:00 2001 From: Oliver Kopp Date: Thu, 22 Oct 2026 23:12:45 +0200 Subject: [PATCH 001/136] Begin refinement Co-Authored-By: Claude Fable 5.1 --- generator-latex-template | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/generator-latex-template b/generator-latex-template index 101bb03e..63193879 160000 --- a/generator-latex-template +++ b/generator-latex-template @@ -1 +1 @@ -Subproject commit 101bb03eda48808de62df4a7a7974e87ffc0f7f8 +Subproject commit 63193879244e128ed88400e74c4e1a3ac3665ff1 From f0ca1f790cd18503e3600e98aa862eafecd12806 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Thu, 22 Oct 2026 21:13:20 +0000 Subject: [PATCH 002/136] Update files based on generated files by template generator --- .aspell.conf | 5 - .aspell.de.pws | 37 +- .aspell.en.pws | 37 +- .dockerignore | 2 +- .github/dependabot.yml | 3 - .github/workflows/check.yml | 146 ++-- .gitignore | 24 +- .textlintrc.json | 12 +- .vscode/extensions.json | 6 +- Dockerfile | 1 - Makefile | 115 +-- README.md | 440 +++++------ Texlivefile | 8 - _latexmkrc | 54 ++ docs/latex-setup.md | 226 ++---- docs/thesis-checklist.md | 2 +- localSettings.yaml | 4 - main-english-thu.tex | 1447 +++++++++++++++++++++++++++++------ vscode.settings.json | 25 +- 19 files changed, 1652 insertions(+), 942 deletions(-) create mode 100644 _latexmkrc diff --git a/.aspell.conf b/.aspell.conf index 6eb485c8..ec61d9bf 100644 --- a/.aspell.conf +++ b/.aspell.conf @@ -1,17 +1,13 @@ add-tex-command "minted options" ppppppppppppppppppppppp add-tex-command @ifundefined pppppp -add-tex-command AtEndDocument p add-tex-command Cref p add-tex-command DeclareFontFamily ppp add-tex-command DeclareFontShape pppppp add-tex-command DeclareMathSymbol ppppp add-tex-command DeclareSymbolFont pppppp -add-tex-command defRQ Pp add-tex-command DisableLigatures p add-tex-command FXRegisterAuthor ppp add-tex-command PassOptionsToPackage pp -add-tex-command refRQ p -add-tex-command refRQFull p add-tex-command RequirePackage op add-tex-command begin pop add-tex-command BeginAccSupp p @@ -44,7 +40,6 @@ add-tex-command setmathfont ooooppppppppppp add-tex-command setminted ppppppp add-tex-command setmonofont ooooppppppppppp add-tex-command setsansfont oooooooopppppppppppp -add-tex-command setupRefEnum opp add-tex-command tcbinputlisting ppppppppppppppppppppppp add-tex-command texttt p add-tex-command tikzpicture op diff --git a/.aspell.de.pws b/.aspell.de.pws index 49307e48..2ad66cde 100644 --- a/.aspell.de.pws +++ b/.aspell.de.pws @@ -1,4 +1,4 @@ -personal_ws-1.1 de 169 utf-8 +personal_ws-1.1 de 134 utf-8 ACM Access Atlantic @@ -6,11 +6,9 @@ BPEL BPMN Bei Cleveref -Crossmark Das Database Diag -FancyVerbLine Firstname Fließtext Geänderter @@ -22,16 +20,10 @@ Kommentar LaTeX LaTeXing Lastname -Lua -LuaLaTeX Manuelle Markierter Markierung -MetaPost -MetaUML North -Npn -Nx OMG ORCID OldStyle @@ -42,18 +34,14 @@ Projects RDBMS RGB Rückverweise -StepLineNo -TODO TODOs Textfarbe Thesis Treaty UML -VV Vorwärtsverweise Worten Zcref -Zref abbreviationdot aboveskip acmnumeric @@ -69,7 +57,6 @@ belowskip breaklines category cls -colortbl commentstyle cref da @@ -79,12 +66,9 @@ der dwarflike eclipseKeywords eclipseStrings -edef ein einigen enquote -enumitem -eq error escapeinside ff @@ -92,7 +76,6 @@ firstline firstnumber flXML fontsize -fquote fr funktioniert für @@ -100,7 +83,6 @@ geändert gp html hypertext -inparaenum ist itemizations json @@ -113,56 +95,39 @@ linenos longplural lst lstlisting -luamplib markup -md microtype mindflow -monospaced morecomment -nTF nato nd nm -nn -nnn -nnnn noch numbersep numberstyle nur oldstyle paralist -pdfcomment powerset produziert pygments -quickstart rdbms -refstepcounter -renderers seit shortplural showstringspaces siunitx -soulpos stepnumber -str stringstyle subcaption subfig subfigure subfigures -tbl tion -tl -tmpa tt vorausverweist werden wird wurde -xcolor xleftmargin zcref zref diff --git a/.aspell.en.pws b/.aspell.en.pws index b696ecb9..4fc3ae15 100644 --- a/.aspell.en.pws +++ b/.aspell.en.pws @@ -1,15 +1,13 @@ -personal_ws-1.1 en 173 utf-8 +personal_ws-1.1 en 138 utf-8 ACM Atlantic BPEL BPMN Bei Cleveref -Crossmark Das Database Diag -FancyVerbLine Firstname Geänderter Hier @@ -20,16 +18,10 @@ Kommentar LaTeX LaTeXing Lastname -Lua -LuaLaTeX Manuelle Markierter Markierung -MetaPost -MetaUML North -Npn -Nx OMG ORCID OldStyle @@ -39,18 +31,14 @@ Practitioner RDBMS RGB ScienceOS -StepLineNo -TODO TODOs Textfarbe Treaty UML Ulm -VV Wikimedia Worten Zcref -Zref abbreviationdot aboveskip acmnumeric @@ -67,7 +55,6 @@ breakatwhitespace breaklines category cls -colortbl commentstyle compat cref @@ -78,12 +65,9 @@ der dwarflike eclipseKeywords eclipseStrings -edef ein einigen enquote -enumitem -eq error escapeinside ff @@ -91,7 +75,6 @@ firstline firstnumber flXML fontsize -fquote fr funktioniert für @@ -100,7 +83,6 @@ gnuplot gp html hypertext -inparaenum ist itemizations json @@ -114,59 +96,42 @@ longplural longtable lst lstlisting -luamplib markup -md microtype mindflow -monospaced morecomment -nTF nato nd nm -nn -nnn -nnnn noch numbersep numberstyle nur oldstyle paralist -pdfcomment pgfplots powerset produziert programmatically pygments -quickstart rdbms -refstepcounter -renderers seit shortplural showstringspaces siunitx -soulpos stepnumber -str stringstyle subcaption subfig subfigure subfigures -tbl tikz tion -tl -tmpa tt werden wird wkrauth wurde -xcolor xleftmargin zcref zref diff --git a/.dockerignore b/.dockerignore index 87009925..89a4abe7 100644 --- a/.dockerignore +++ b/.dockerignore @@ -4,7 +4,7 @@ generator-latex-template main-english.pdf main-english-*.pdf -figures/*.pdf_tex +graphics/*.pdf_tex # spelling *.spell.bad diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 96b8d89d..88ecd370 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -4,6 +4,3 @@ updates: directory: '/' schedule: interval: 'weekly' - groups: - actions: - patterns: ["*"] diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index c85451f6..4d375ec8 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -16,9 +16,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Set up Git repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + uses: actions/checkout@v7 - name: Install TeX Live - uses: zauguin/install-texlive@6671d0c62046c7e349fe154d5208fe746b07e037 # v4.4.0 + uses: zauguin/install-texlive@v4 with: package_file: '${{ github.workspace }}/Texlivefile' texlive_version: 2026 @@ -27,10 +27,13 @@ jobs: updmap -sys texhash tlmgr generate language --rebuild-sys + if [ ! -f "latexmkrc" ]; then + cp "_latexmkrc" "latexmkrc" + fi - run: latexmk main-english - # Highlight misspelled words in the PDF - - uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3 + # Highlight mis-spelled words in the PDF + - uses: awalsh128/cache-apt-pkgs-action@latest with: packages: aspell aspell-en aspell-de version: 1.0 @@ -43,29 +46,18 @@ jobs: # Needs more adaption for scientific thesis; therefore disabled if: ${{ false }} run: | - for tex in *.tex chapters-*/*.tex content-markdown*.md chapters-*/*.md; do - [ -e "$tex" ] || continue - if [[ "en" == "de" && ( "$tex" == thesis-example* || "$tex" == chapters-de/* ) ]]; then + for tex in $(ls *.tex content/*.tex 2>/dev/null); do + if [[ "en" == "de" && "$tex" == thesis-example* ]]; then continue fi # The lualatex package "spelling" requires the content to be in a file ending with ".spell.bad" - # Markdown files may contain LaTeX commands and references (<#id>, {#id}), which are no words. - if [[ "$tex" == *.md ]]; then - sed -E 's/\\[A-Za-z]+//g; s/<#[^>]*>//g; s/\{#[^}]*\}//g' "$tex" | aspell --mode=markdown\ - -l en_US\ - --encoding=utf-8\ - --conf=./.aspell.conf\ - -p ./.aspell.en.pws list\ - | sort | uniq >> main-english.spell.bad - else - aspell --mode=tex\ - -l en_US\ - --encoding=utf-8\ - --conf=./.aspell.conf\ - -p ./.aspell.en.pws list\ - < "$tex" | sort | uniq >> main-english.spell.bad - fi + aspell --mode=tex\ + -l en_US\ + --encoding=utf-8\ + --conf=./.aspell.conf\ + -p ./.aspell.en.pws list\ + < $tex | sort | uniq >> main-english.spell.bad done - run: latexmk main-english @@ -76,7 +68,7 @@ jobs: echo '```' >> $GITHUB_STEP_SUMMARY texlogsieve main-english.log | tee -a "$GITHUB_STEP_SUMMARY" || true echo '```' >> $GITHUB_STEP_SUMMARY - - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + - uses: actions/upload-artifact@v7 with: name: test-result path: | @@ -87,9 +79,9 @@ jobs: runs-on: ubuntu-latest steps: - name: Set up Git repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + uses: actions/checkout@v7 - name: Install TeX Live - uses: zauguin/install-texlive@6671d0c62046c7e349fe154d5208fe746b07e037 # v4.4.0 + uses: zauguin/install-texlive@v4 with: package_file: '${{ github.workspace }}/Texlivefile' texlive_version: 2026 @@ -110,7 +102,7 @@ jobs: # echo "## TeXcount LaTeX interpretation" >> $GITHUB_STEP_SUMMARY # echo "" >> $GITHUB_STEP_SUMMARY # cat "texcount.html-body" >> $GITHUB_STEP_SUMMARY - - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + - uses: actions/upload-artifact@v7 with: name: word-count path: | @@ -122,23 +114,28 @@ jobs: # Disabled: the example content trips too many aspell false positives to maintain if: false runs-on: ubuntu-latest - # The DANTE e.V. image contains aspell with English and German dictionaries - container: danteev/texlive:2026-C - # In a container, steps run with sh by default - defaults: - run: - shell: bash steps: - name: Set up Git repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + uses: actions/checkout@v7 + + # Original action does not work well - see https://github.com/awalsh128/cache-apt-pkgs-action/pull/136 + # The action is not updated - and thus the dictionaries are not updated + - uses: awalsh128/cache-apt-pkgs-action@latest + with: + packages: aspell aspell-en aspell-de + version: 1.0 + execute_install_scripts: true + - name: post-setup aspell + # refs https://github.com/awalsh128/cache-apt-pkgs-action/issues/157 + run: | + sudo apt-get install -y aspell-en aspell-de - name: aspell run: | echo "| file | status |" >> $GITHUB_STEP_SUMMARY echo "| -- | -- |" >> $GITHUB_STEP_SUMMARY failure=0 - for tex in *.tex chapters-*/*.tex content-markdown*.md chapters-*/*.md; do - [ -e "$tex" ] || continue - if [[ "en" == "de" && ( "$tex" == thesis-example* || "$tex" == chapters-de/* ) ]]; then + for tex in $(ls *.tex content/*.tex 2>/dev/null); do + if [[ "en" == "de" && "$tex" == thesis-example* ]]; then echo "$tex skipped" continue fi @@ -147,23 +144,17 @@ jobs: # Pick the dictionary that matches the file's language: the "-de" # variants are German, everything else uses the document's language. case "$tex" in - *-de.tex|*-de-*.tex|*.de.md|chapters-de/*) aspell_lang="-l de_DE --run-together"; aspell_pws=de ;; - chapters-en/*) aspell_lang="-l en_US"; aspell_pws=en ;; + *-de.tex|*-de-*.tex) aspell_lang="-l de_DE --run-together"; aspell_pws=de ;; *) aspell_lang="-l en_US"; aspell_pws=en ;; esac - # Words are output in the order they appear in the document. - # Markdown files may contain LaTeX commands and references (<#id>, {#id}), which are no words. - if [[ "$tex" == *.md ]]; then - words=$(sed -E 's/\\[A-Za-z]+//g; s/<#[^>]*>//g; s/\{#[^}]*\}//g' "$tex" | aspell --mode=markdown $aspell_lang --encoding=utf-8 --conf=./.aspell.conf -p ./.aspell.$aspell_pws.pws list | tr '\n' ' ') - else - words=$(aspell --mode=tex $aspell_lang --encoding=utf-8 --conf=./.aspell.conf -p ./.aspell.$aspell_pws.pws list < "$tex" | tr '\n' ' ') - fi + # Words are output in the order they appear in the document + words=$(aspell --mode=tex $aspell_lang --encoding=utf-8 --conf=./.aspell.conf -p ./.aspell.$aspell_pws.pws list < $tex | tr '\n' ' ') if [ -z "$words" ]; then echo "| $tex | ✅ |" >> $GITHUB_STEP_SUMMARY else echo "| $tex | ❌ $words |" >> $GITHUB_STEP_SUMMARY - if [[ "$tex" == "main-english.tex" || "$tex" == chapters-en/* || "$tex" == content-markdown.md ]]; then + if [[ "$tex" == "main-english.tex" ]]; then failure=1 fi fi @@ -177,8 +168,8 @@ jobs: runs-on: ubuntu-latest steps: - name: Set up Git repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + uses: actions/checkout@v7 + - uses: actions/setup-node@v7 with: node-version: '22' - name: Lint English prose with textlint @@ -186,17 +177,9 @@ jobs: # Report-only: findings show up as annotations, the job does not fail. # Rules come from .textlintrc.json. Only English documents (marked by # "% !TeX spellcheck = en-US") are linted: write-good targets English. - # The English Markdown files (content-markdown.md, chapters-en/*.md) belong to them. - # The English chapters (chapters-en/*.tex) belong to them. - files=() - for tex in *.tex chapters-en/*.tex chapters-en/*.md; do - [ -e "$tex" ] || continue - if [[ "$tex" == chapters-en/* || "$tex" == *.md ]] || grep -q '^% !TeX spellcheck = en' "$tex"; then - files+=("$tex") - fi - done - if [ ${#files[@]} -eq 0 ]; then - echo "No English files to lint." >> "$GITHUB_STEP_SUMMARY" + files=$(grep -l '^% !TeX spellcheck = en' *.tex || true) + if [ -z "$files" ]; then + echo "No English .tex files to lint." >> "$GITHUB_STEP_SUMMARY" exit 0 fi npx --yes \ @@ -205,56 +188,25 @@ jobs: --package textlint-filter-rule-allowlist \ --package textlint-rule-terminology \ --package textlint-rule-write-good \ - textlint --format github "${files[@]}" \ + textlint --format github $files \ | sed "s|${GITHUB_WORKSPACE}/||g" | tee annotations.txt || true count=$(grep -c '^::\(error\|warning\)' annotations.txt || true) - echo "textlint reported ${count} finding(s) in: $(IFS=,; echo "${files[*]}")" >> "$GITHUB_STEP_SUMMARY" - typos: - runs-on: ubuntu-latest - steps: - - name: Set up Git repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - # Finds common misspellings (configured in .typos.toml) - - uses: crate-ci/typos@7f9d0819ca1c008ade73f4b41fa9d258d48f605b # v1.51.1 - textidote: - runs-on: ubuntu-latest - # The DANTE e.V. image contains TeXtidote - container: danteev/texlive:2026-C - # In a container, steps run with sh by default - defaults: - run: - shell: bash - steps: - - name: Set up Git repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Check spelling, grammar, and style with TeXtidote - run: | - # Report-only: findings show up as annotations, the job does not fail. - # TeXtidote (https://github.com/sylvainhalle/textidote) reads its options from .textidote. - textidote --output singleline --no-color main-english.tex > textidote.txt || true - # TeXtidote mixes up the text of \include lines, so .textidote removes them and each chapter is checked on its own - for tex in chapters-en/*.tex chapters-en/*.md; do - [ -e "$tex" ] || continue - textidote --output singleline --no-color --read-all "$tex" >> textidote.txt || true - done - # A finding looks like: file.tex(L25C1-L25C25): message "excerpt" - perl -ne 'if (/^(.+?)\(L(\d+)C(\d+)-L(\d+)C(\d+)\): (.*)$/) { my ($f, $l, $c, $el, $ec, $m) = ($1, $2, $3, $4, $5, $6); $m =~ s/%/%25/g; print "::warning file=$f,line=$l,col=$c,endLine=$el,endColumn=$ec,title=TeXtidote::$m\n" }' textidote.txt - echo "TeXtidote reported $(grep -c . textidote.txt) finding(s) in main-english.tex and its chapters" >> "$GITHUB_STEP_SUMMARY" + echo "textlint reported ${count} finding(s) in: ${files//$'\n'/, }" >> "$GITHUB_STEP_SUMMARY" indent: runs-on: ubuntu-latest steps: - name: Set up Git repository - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - uses: awalsh128/cache-apt-pkgs-action@553a35bb8ebd9fcabcb1c9451aa4c98e1b4ca8a9 # v1.6.3 + uses: actions/checkout@v7 + - uses: awalsh128/cache-apt-pkgs-action@latest with: packages: libyaml-tiny-perl libfile-homedir-perl version: 1.0 execute_install_scripts: true - name: Install latexindent - uses: zauguin/install-texlive@6671d0c62046c7e349fe154d5208fe746b07e037 # v4.4.0 + uses: zauguin/install-texlive@v4 with: packages: latexindent texlive_version: 2026 - - run: make format LOCAL=1 + - run: make format - name: No changes made by latexindent run: git diff --exit-code diff --git a/.gitignore b/.gitignore index b5e312ac..cc01c3e2 100644 --- a/.gitignore +++ b/.gitignore @@ -2,10 +2,17 @@ main-english.pdf main-english-*.pdf figures/*.pdf_tex +main-english.tex +main-english-university-of-hamburg.tex +main-german.tex +main-german-university-of-hamburg.tex +main-minted-english.tex +main-minted-english-university-of-hamburg.tex +main-minted-german.tex +main-minted-german-university-of-hamburg.tex + # glossaries -*.glg-abr *.glo-abr -*.gls-abr # glossaries-extra *.ist @@ -18,17 +25,6 @@ figures/*.pdf_tex *-plantuml.latex *-plantuml.txt -# ltmermaid (rendered Mermaid diagrams) -mermaid/ - -# TeXtidote (make spellcheck-textidote) -textidote.html -*.textidote.html - -# markdown package (cache of converted Markdown) -_markdown_*/ -*.markdown.in - # latexindent *.bak *.bak? @@ -494,8 +490,6 @@ Backup of *.doc* !.vscode/launch.json !.vscode/extensions.json !.vscode/*.code-snippets -# Word lists of LTeX+ (see "make dictionaries") -!.vscode/ltex.*.txt # Local History for Visual Studio Code .history/ diff --git a/.textlintrc.json b/.textlintrc.json index 9d4d6748..9a45f873 100644 --- a/.textlintrc.json +++ b/.textlintrc.json @@ -4,22 +4,14 @@ }, "filters": { "allowlist": { - "allow": [ - "/\\bonly\\b/i", - "/\\bFinally,/", - "/\\\\[A-Za-z@]+_[A-Za-z@_]+:[A-Za-z]*/", - "/#[A-Za-z]+:[A-Za-z0-9_-]+/", - "/\\{markdown\\} package/" - ] + "allow": ["/\\bonly\\b/i"] } }, "rules": { "terminology": true, "write-good": { "tooWordy": false, - "whitelist": [ - "only" - ] + "whitelist": ["only"] } } } diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 22c18cfe..feae379f 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,9 +1,7 @@ { "recommendations": [ - "james-yu.latex-workshop", + "manhen.latex-workshop-2", "tecosaur.latex-utilities", - "ltex-plus.vscode-ltex-plus", - "jabref.jabref-4-vscode", - "davidanson.vscode-markdownlint" + "ltex-plus.vscode-ltex-plus" ] } diff --git a/Dockerfile b/Dockerfile index a22a6622..add78732 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,3 +1,2 @@ FROM registry.gitlab.com/islandoftex/images/texlive:latest - WORKDIR /workdir diff --git a/Makefile b/Makefile index 8743192d..919cfef6 100644 --- a/Makefile +++ b/Makefile @@ -3,35 +3,8 @@ ## Required for thumbpdf as latexmk does not support thumbpdf by itself latexcompiler = lualatex -## PDF viewer: Sumatra PDF on Windows (reloads the PDF automatically), the default viewer otherwise -ifeq ($(OS),Windows_NT) -viewer = 'C:/Program Files/SumatraPDF/SumatraPDF.exe' -else ifeq ($(shell uname -s),Darwin) -viewer = open -else -viewer = xdg-open -endif - -## The LaTeX tools run in the TeX Live Docker image (see README.md); "make LOCAL=1" uses the local LaTeX distribution -ifeq ($(LOCAL),) -ifeq ($(OS),Windows_NT) -RUN = docker run --rm -v "$(CURDIR):/workdir" -w /workdir registry.gitlab.com/islandoftex/images/texlive:latest -else -RUN = docker run --rm -u $(shell id -u):$(shell id -g) -e HOME=/tmp -v "$(CURDIR):/workdir" -w /workdir registry.gitlab.com/islandoftex/images/texlive:latest -endif -endif - -## The spell checkers (aspell, TeXtidote) run in the Docker image by DANTE e.V., which contains them; "make LOCAL=1" uses local installations -## LINT_IT is interactive (aspell -c) -ifeq ($(LOCAL),) -ifeq ($(OS),Windows_NT) -LINT = docker run --rm -v "$(CURDIR):/workdir" -w /workdir danteev/texlive:2026-C -LINT_IT = docker run --rm -it -v "$(CURDIR):/workdir" -w /workdir danteev/texlive:2026-C -else -LINT = docker run --rm -u $(shell id -u):$(shell id -g) -e HOME=/tmp -v "$(CURDIR):/workdir" -w /workdir danteev/texlive:2026-C -LINT_IT = docker run --rm -it -u $(shell id -u):$(shell id -g) -e HOME=/tmp -v "$(CURDIR):/workdir" -w /workdir danteev/texlive:2026-C -endif -endif +## evince at linux +viewer = 'C:/Program Files (x86)/SumatraPDF/SumatraPDF.exe' ## Editor editor = gedit @@ -44,9 +17,7 @@ LITERATURE = bibliography.bib ## Derived file names SRC = $(shell basename $(MASTER_TEX) .tex) -TEX_FILES = $(wildcard *.tex) -## All main files, including variants of MASTER_TEX (e.g., other languages): "make format" indents each of them and the chapters -MAIN_TEX_FILES = $(wildcard main*.tex) +TEX_FILES = $(wildcard *.tex content/*.tex) GFX_FILES = $(wildcard figures/*) PDF = $(SRC).pdf @@ -60,24 +31,23 @@ date=$(shell date +%Y%m%d%H%M) ## was wird gemacht, falls nur make aufgerufen wird +## hier sollte noch der aspell check rein für jedes file einzeln über for schleife all: $(PDF) - -## Targets that do not create a file of their name; $(PDF) is phony as latexmk decides whether to rebuild -.PHONY: all compile $(PDF) clean final mrproper pdf stand html view edit spellcheck spellcheck-aspell spellcheck-textidote dictionaries log showundef format indent split-sentences +.PHONY: $(PDF) compile: $(PDF) $(PDF): $(MASTER_TEX) $(LITERATURE) $(TEX_FILES) $(GFX_FILES) - $(RUN) latexmk $(MASTER_TEX) + latexmk $(MASTER_TEX) clean: - $(RUN) latexmk -C + latexmk -C ## Endversion - mit eingebauter Seitenvorschau ## Mehrere Durchlaeufe, da bei longtable einige runs mehr vonnoeten sind... final: $(PDF) - $(RUN) thumbpdf $(PDF) - $(RUN) $(latexcompiler) $(MASTER_TEX) + thumbpdf $(PDF) + $(latexcompiler) $(MASTER_TEX) mrproper: clean rm -f *~ @@ -92,7 +62,7 @@ stand: $(PDF) html: clean pdf rm $(AUX) - $(RUN) htlatex $(SRC) "html,word,charset=utf8" " -utf8" + htlatex $(SRC) "html,word,charset=utf8" " -utf8" # Tools @@ -107,73 +77,32 @@ edit: # Support -## Spell checking: "make spellcheck" runs all spell checkers, "make spellcheck-" one of them -spellcheck: spellcheck-aspell spellcheck-textidote - -## Interactive spell checking with aspell +## Rechtschreibung +## +## Das Ganze am Besten vor der final und als eigene Version ala "make aspell" ## ## .aspell.conf - zu ignorierende LaTeX-Befehle ## Schreiben der LaTeX-Befehle in eine config Dateiname. Sieht so aus: ## add-tex-command democommand PO // PO := prüfe []{} ;; po := ignoriere []{} ## ## .aspell.en.pws - persönliches Wörterbuch -spellcheck-aspell: - for tex in *.tex chapters-en/*.tex; do \ - [ -e "$$tex" ] || continue; \ - $(LINT_IT) aspell --mode=tex -l en_US --encoding=utf-8 --conf=./.aspell.conf -p ./.aspell.en.pws -c "$$tex" || exit 1; \ - done - for md in chapters-en/*.md; do \ - [ -e "$$md" ] || continue; \ - $(LINT_IT) aspell --mode=markdown -l en_US --encoding=utf-8 --conf=./.aspell.conf -p ./.aspell.en.pws -c "$$md" || exit 1; \ - done - -## Spelling, grammar, and style with TeXtidote (https://github.com/sylvainhalle/textidote): writes textidote.html and chapters-en/*.textidote.html -## The options are in .textidote (its --check en is overridden here). -spellcheck-textidote: - @# TeXtidote exits with the number of findings, which is no failure here - $(LINT) textidote --check en --output html $(MASTER_TEX) > textidote.html || test -s textidote.html - @# TeXtidote mixes up the text of \include lines, so .textidote removes them and each chapter is checked on its own - for tex in chapters-en/*.tex chapters-en/*.md; do \ - [ -e "$$tex" ] || continue; \ - $(LINT) textidote --check en --output html --read-all "$$tex" > "$${tex%.*}.textidote.html" || test -s "$${tex%.*}.textidote.html"; \ - done - @echo "Reports: textidote.html and chapters-en/*.textidote.html" - -## Merge the word lists of the spell checkers: a word added to .aspell..pws or (e.g., by -## "Add to dictionary" in VS Code) to .vscode/ltex.dictionary..txt ends up in both and in .textidote.dict. -## aspell word lists cannot contain hyphenated words; these words are added to the other lists. -HYPHENATED_WORDS = markdown-latex-quickstart pgf-umlsd zref-clever Zref-clever zref-vario Zref-vario -dictionaries: - mkdir -p .vscode - for pair in en:en-US de:de-DE; do \ - lang=$${pair%%:*}; pws=".aspell.$$lang.pws"; ltex=".vscode/ltex.dictionary.$${pair#*:}.txt"; \ - [ -e "$$pws" ] || continue; \ - { tail -n +2 "$$pws"; if [ -e "$$ltex" ]; then cat "$$ltex"; fi; printf '%s\n' $(HYPHENATED_WORDS); } | grep -v '^$$' | LC_ALL=C sort -u > "$$ltex.tmp"; \ - mv "$$ltex.tmp" "$$ltex"; \ - grep -v -e - "$$ltex" > "$$pws.tmp"; \ - { echo "personal_ws-1.1 $$lang $$(wc -l < "$$pws.tmp" | tr -d ' ') utf-8"; cat "$$pws.tmp"; } > "$$pws"; \ - rm "$$pws.tmp"; \ - done - cat .vscode/ltex.dictionary.*.txt | LC_ALL=C sort -u > .textidote.dict - -## Show only the relevant messages of the last LaTeX run -log: - $(RUN) texlogsieve --no-heartbeat $(SRC).log +aspell: + for tex in $(TEX_FILES); + do + aspell --mode=tex -l en_US --encoding=utf-8 --conf=./.aspell.conf -p ./.aspell.en.pws -c $$tex; + done showundef: - grep undefined $(SRC).log + grep undefined $(LOG) ## Reformatierung format: - for f in $(MAIN_TEX_FILES) chapters-*/*.tex; do \ - [ -e "$$f" ] || continue; \ - $(RUN) latexindent -l -s -sl -w "$$f" || exit 1; \ - done + latexindent -l -s -sl -w $(SRC) indent: - $(RUN) latexindent -y="indentPreamble:1,defaultIndent:' '" -m -w $(SRC) + latexindent -y="indentPreamble:1,defaultIndent:' '" -m -w $(SRC) split-sentences: - $(RUN) latexindent -m -l -s -sl -w $(SRC) + latexindent -m -l -s -sl -w $(SRC) diff --git a/README.md b/README.md index e26d8cff..edb9584b 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,20 @@ # LaTeX Template for a Scientific Thesis This template is a general template for scientific theses. -Currently, it is the unofficial LaTeX template for Master, Bachelor, Diploma, and Student Theses at the computer science departments listed below, each with example PDFs; other departments are untested. -The template will be extended to support theses from more institutions. +Currently, it is the unofficial LaTeX template for Master, Bachelor, Diploma, and Student Theses at following institutions: -The LaTeX snippets this template is assembled from can be inspected at . - -## Supported institutions - -### University of Stuttgart, Computer Science +- University of Stuttgart, Computer Science -- 🇺🇸 [English example](https://latextemplates.github.io/scientific-thesis-template/main-english.pdf) -- 🇺🇸 [English example using the listings package (instead of minted) for source code](https://latextemplates.github.io/scientific-thesis-template/main-basic-listings-english.pdf) -- 🇩🇪 [German example](https://latextemplates.github.io/scientific-thesis-template/main-german.pdf) -- 🇩🇪 [German example using the listings package (instead of minted) for source code](https://latextemplates.github.io/scientific-thesis-template/main-basic-listings-german.pdf) + - 🇺🇸 [English example](https://latextemplates.github.io/scientific-thesis-template/main-english.pdf) + - 🇺🇸 [English example with minted and PlantUML](https://latextemplates.github.io/scientific-thesis-template/main-minted-english.pdf) + - 🇺🇸 [English example with minted and PlantUML (University of Hamburg)](https://latextemplates.github.io/scientific-thesis-template/main-minted-english-university-of-hamburg.pdf) + - 🇩🇪 [German example](https://latextemplates.github.io/scientific-thesis-template/main-german.pdf) + - 🇩🇪 [German example with minted and PlantUML](https://latextemplates.github.io/scientific-thesis-template/main-minted-german.pdf) + - 🇩🇪 [German example with minted and PlantUML (Universität Hamburg)](https://latextemplates.github.io/scientific-thesis-template/main-minted-german-university-of-hamburg.pdf) -### Universität Hamburg, Computer Science +The template will be extended to support theses from different institutions. -- 🇺🇸 [English example](https://latextemplates.github.io/scientific-thesis-template/main-english-university-of-hamburg.pdf) -- 🇩🇪 [German example](https://latextemplates.github.io/scientific-thesis-template/main-german-university-of-hamburg.pdf) - -### Technische Hochschule Ulm (THU), Computer Science - -- 🇺🇸 [English example](https://latextemplates.github.io/scientific-thesis-template/main-english-thu.pdf) -- 🇩🇪 [German example](https://latextemplates.github.io/scientific-thesis-template/main-german-thu.pdf) +For [architectural decision records](https://adr.github.io) see [docs/adr](docs/adr/). ## Quick start @@ -37,207 +28,136 @@ The LaTeX snippets this template is assembled from can be inspected at . + ## Writing your thesis - Read [Student Thesis Projects](https://vdf.ch/product/student-thesis-projects-en.html) by Lichter, Ludewig, Deininger, and Schneider. The open-access book explains how to organize, conduct, write, and present a thesis. - Before handing in, work through the [thesis checklist](docs/thesis-checklist.md). -## Benefits +## Usage -Following features are enabled in this template: +- `main-english.tex` is the main document +- Use "lualatex + biblatex" in your TeX editor or `latexmk main-english` / `make` in the command line -- (Optional) Typesetting of listings using advanced highlighting powered by the [minted] package. - `minted` provides better output than [listings], but requires [latexminted] to be installed. -- Numbered research questions: `\defRQ` prints "Research Question 1 (RQ1)", `\refRQ` references it as "RQ1". - This is enabled by the [refenums](https://github.com/koppor/refenums) package; `refenums.sty` is part of this repository, because TeX Live contains an older version. -- Generated PDF allows for copy and paste of text without getting words with [ligatures](https://en.wikipedia.org/wiki/Typographic_ligature) such as "workflow" destroyed. - With pdfLaTeX, this is enabled by `glyphtounicode`, which encodes ligatures (such as fl) using unicode characters; LuaLaTeX does this by itself. -- Ligatures are removed if they are typeset at the wrong place. - This is enabled by the [selnolig](https://tex.meta.stackexchange.com/questions/2884/new-package-selnolig-that-automates-suppression-of-typographic-ligatures) package. -- Support of hyperlinked references without extra color thanx to [hyperref]. -- Better breaking of long URLs. -- Support for `\powerset` command. -- Support todos as pdf annotations. This is enabled by the [pdfcomment] package. -- [microtypographic extensions](https://www.ctan.org/pkg/microtype) for a better look of the paper. -- Modern packages such as [microtype], [zref-clever], [csquotes], [paralist], [hyperref], [hypcap], [upquote], [booktabs]. -- LaTeX compilation using the modern [lualatex] compiler. - For older systems, [pdflatex](https://en.wikipedia.org/wiki/PdfTeX) is still supported. -- [biblatex]+[biber] instead of plain [bibtex] to have a more intuitive `.bib` file: - Unicode (UTF-8) is fully supported and commands such as `\citeauthor{...}` work out of the box. See also . -- [latexmk] for easy compilation of the LaTeX document. -- Ready-to-go configuration for [latexindent]. -- Proper hyphenation and microtype for English texts. -- Hints on writing an abstract and thesis by Dirk Fahland. - -### Disabled features +### Using `latexmk` -Following features were not activated for this template. -You can run the [latex template generator] to enable the features. - -Congratulations. You chose to use all available features. - -## Contained directories and files +[latexmk] is a very smart tool for latex compilation. +It executes the latex tools as often as needed to get the final PDF. +(More information about why `latexmk` is great can be found at .) -### Directories +To build the whole document, execute following command. +Note that this requires a working perl installation. -- [chapters-en](chapters-en/), [chapters-de](chapters-de/) One file per chapter (English, German), included by the main file. - The chapter on Markdown is a plain Markdown file (`.md`), included with `\markdownInput` (LuaLaTeX only). - The source code example of the LaTeX hints is a file of its own for each of the minted and listings packages. -- [figures](figures/) Directory containing the figures. - By using LuaLaTex/PDFLaTeX it is possible to use PDF, JPG, and PNG files. We recommend to use PDFs to enable smooth scaling. - -### Files - -- `main-english.tex` - The main `.tex` file loading all LaTeX packages and their configurations. - - Add or remove chapters here - - Adjust title, … here -- [bibliography.bib](bibliography.bib) - Bibliography. [biblatex] format. Manage it with [JabRef]. -- [abbreviations.tex](abbreviations.tex) - Acronyms and abbreviations. -- [commands.tex](commands.tex) - Example LaTeX macros. - -Following additional files are included, which do not need to be adapted: - -- [localSettings.yaml](localSettings.yaml) - Settings for [latexindent](https://ctan.org/pkg/latexindent) -- [Makefile](Makefile) - The Makefile. Builds on latexmk. -- [Texlivefile](Texlivefile) - List of packages required for a minimal TeXLive installation. - -## LaTeX compilation - -Compile either in a Docker container (recommended) or with a LaTeX distribution installed on your machine. - -### Docker-based (recommended) - -The [TeX Live docker image by the Island of TeX](https://gitlab.com/islandoftex/images/texlive#tex-live-docker-image) works the same on Windows, macOS, and Linux. -It ships a complete TeX Live including `latexmk`, `biber`, `latexindent`, Python, and [latexminted]. -Thus, `minted` works out of the box - also on Windows, without a separate Python setup. - -1. Install [Docker](https://docs.docker.com/get-started/get-docker/) ([Docker Desktop](https://docs.docker.com/desktop/) on Windows and macOS). -1. Open a terminal in the directory of this document and compile in the container. - The first run downloads the image (approx. 3 GB); its tag selects the TeX Live version of this template. - - Windows (PowerShell): - - ```powershell - docker run --rm -v "${PWD}:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest latexmk main-english - ``` - - Windows (Command Prompt): - - ```cmd - docker run --rm -v "%cd%:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest latexmk main-english - ``` - - Linux and macOS: - - ```shell - docker run --rm -v "$PWD:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest latexmk main-english - ``` - -1. Optional: Let VS Code compile in the container, see ["VS Code configuration"](#vs-code-configuration). - -If you need additional tools in the image, extend the generated `Dockerfile`, build it with `docker build -t ltg .`, and use `ltg` instead of the image name. - -### Traditional - -Install a LaTeX distribution on your machine: - -- Windows: Recent [MiKTeX](http://miktex.org/). MiKTeX installation hints are given at . -- macOS: Recent [TeX Live](https://www.tug.org/texlive/) (e.g. through [MacTeX](https://tug.org/mactex/)) - Try `sudo tlmgr update --all` if you encounter issues with biblatex -- Linux: Recent TeX Live distribution +```bash +latexmk main-english +``` -See for refined installation instructions. +To enable latexmk, please move `_latexmkrc` to `latexmkrc`. -To have `minted` running with a traditional installation, you have to do following steps on Windows (the Docker image already contains all of this): +If you want automatic compilation use following command: -1. Install python: `choco install python` - that uses [chocolatey](https://chocolatey.org/) to install Python -2. Install [latexminted]: `pip install latexminted` - that uses the Python package manager to install the minted library +```bash +latexmk -pvc main-english +``` -### latexmk hints +This will also open a [Sumatra PDF] and only works with the supplied configuration. -[latexmk] runs the LaTeX tools (e.g., lualatex and biber) as often as needed to get the final PDF ([why `latexmk` is great](https://tex.stackexchange.com/a/249243/9075)). -It reads its configuration from `.latexmkrc` in the directory of the document. -Overleaf reads `.latexmkrc`, too, so the "Compiler" setting of the Overleaf project does not matter; select TeX Live 2026 there. -To use the configuration for all your documents, put it at [the right place](http://tex.stackexchange.com/a/41149/9075). +#### latexmk configuration -Build the document: +This repository ships a `.latexmkrc` which is read by latexmk. +In case there is a `_latexmkrc` file, you need to rename it to `.latexmkrc`. +It is configured for Windows and especially sets Sumatra PDF as default PDF viewer. +You can make this local configuration a global configuration, when you put it at [the right place](http://tex.stackexchange.com/a/41149/9075). -```bash -latexmk main-english -``` +If you want to add more packages, configure it there. +For instance, for support of `makeglossaries` see . -In the Docker-based setup, put the `docker run ...` part from ["Docker-based (recommended)"](#docker-based-recommended) in front, or just run `make`. -In the traditional setup, `latexmk` needs Perl (TeX Live ships it; with MiKTeX, install it, e.g., via `choco install strawberryperl`). +### Debugging LaTeX errors -To recompile on every change and open the PDF, run: +In case something goes wrong, you can instruct the LaTeX compiler to stop at the first error: ```bash -latexmk -pvc main-english +lualatex --synctex=1 --shell-escape main-english ``` -On Windows, the configuration opens the PDF in [Sumatra PDF], which reloads the PDF automatically. - -## Tool hints +Run `biber main-english` to get the bibliography rendered (execute `lualatex` afterwards). ### Advanced usage On the command line, there are additional features: -- `make` builds the PDF in the Docker container; `make LOCAL=1` uses your local LaTeX distribution (this works for all `make` targets) - `latexmk -C` or `make clean` for cleaning up -- `make log` shows only the relevant messages of the last LaTeX run (using [texlogsieve](https://ctan.org/pkg/texlogsieve)) - `make format` to reformat the `.tex` files (one sentence per line and indent) -- `make spellcheck` runs all spell checkers (in the [Docker image by DANTE e.V.](https://hub.docker.com/r/danteev/texlive), which contains them; `make LOCAL=1 spellcheck` uses local installations): - - `make spellcheck-aspell` for interactive spell checking with aspell - - `make spellcheck-textidote` checks spelling, grammar, and style with [TeXtidote](https://github.com/sylvainhalle/textidote) (report in `textidote.html`, for the chapters in `chapters-*/*.textidote.html`) -- `make dictionaries` merges the word lists of the spell checkers (see the FAQ on adding words) +- `make aspell` for interactive spell checking - `make stand`: Creates a new PDF with the current status of the document. - `make view`: Opens the configured viewer - `make mrproper`: Cleans up and removes also editor backup files. -Without `make` (e.g., on Windows), run a target with `make` in the [Docker image by DANTE e.V.](https://hub.docker.com/r/danteev/texlive), which contains `make` and all tools, e.g., `dictionaries`: - -```powershell -docker run --rm -it -v "${PWD}:/workdir" -w /workdir danteev/texlive:2026-C make LOCAL=1 dictionaries -``` - -```bash -docker run --rm -it -u "$(id -u):$(id -g)" -e HOME=/tmp -v "$PWD:/workdir" -w /workdir danteev/texlive:2026-C make LOCAL=1 dictionaries -``` - The `textlint` job of the `Check` workflow reports weakening words (e.g., "clearly", "just") in the English `.tex` files as annotations. Run it locally with `npx` (needs Node.js; rules come from `.textlintrc.json`): ```bash -npx --yes --package textlint --package textlint-plugin-latex2e --package textlint-filter-rule-allowlist --package textlint-rule-terminology --package textlint-rule-write-good textlint main-english.tex chapters-en/*.tex chapters-en/*.md +npx --yes --package textlint --package textlint-plugin-latex2e --package textlint-filter-rule-allowlist --package textlint-rule-terminology --package textlint-rule-write-good textlint main-english.tex ``` -The `textidote` job of the `Check` workflow checks spelling, grammar, and style of English documents with [TeXtidote](https://github.com/sylvainhalle/textidote) and reports its findings as annotations. -Its options are in `.textidote`. -Run it locally with `make spellcheck-textidote`: it writes the report `textidote.html` (for the chapters: `chapters-*/*.textidote.html`). +## Benefits + +Following features are enabled in this template: + +- (Optional) Typesetting of listings using advanced highlighting powered by the [minted] package. + `minted` provides better output than [listings], but requires [latexminted] to be installed. +- Generated PDF allows for copy and paste of text without getting words with [ligatures](https://en.wikipedia.org/wiki/Typographic_ligature) such as "workflow" destroyed. + This is enabled by `glyphtounicode`, which encodes ligatures (such as fl) using unicode characters. +- Ligatures are removed if they are typeset at the wrong place. + This is enabled by the [selnolig](https://tex.meta.stackexchange.com/questions/2884/new-package-selnolig-that-automates-suppression-of-typographic-ligatures) package. +- Support of hyperlinked references without extra color thanx to [hyperref]. +- Better breaking of long URLs. +- Support for `\powerset` command. +- Support todos as pdf annotations. This is enabled by the [pdfcomment] package. +- [microtypographic extensions](https://www.ctan.org/pkg/microtype) for a better look of the paper. +- Modern packages such as [microtype], [zref-clever], [csquotes], [paralist], [hyperref], [hypcap], [upquote], [booktabs]. +- LaTeX compilation using the modern [lualatex] compiler. + For older systems, [pdflatex](https://en.wikipedia.org/wiki/PdfTeX) is still supported. +- [biblatex]+[biber] instead of plain [bibtex] to have a more intuitive `.bib` file: + Unicode (UTF-8) is fully supported and commands such as `\citeauthor{...}` work out of the box. See also . +- [latexmk] for easy compilation of the LaTeX document. +- Ready-to-go configuration for [latexindent]. +- Proper hyphenation and microtype for English texts. +- Hints on writing an abstract and thesis by Dirk Fahland. -### UML diagrams with PlantUML or Mermaid +## Disabled features -The "LaTeX Hints" chapter shows UML diagrams drawn with [MetaUML](https://ctan.org/pkg/metauml) and [pgf-umlsd](https://ctan.org/pkg/pgf-umlsd), which need no further tools. -PlantUML and Mermaid offer a more compact syntax and lay out the diagrams automatically, but need further tools: they are contained in the [Docker image by DANTE e.V.](https://github.com/dante-ev/docker-texlive). -To use them, generate an own copy of this template with the [latex template generator]: +Following features were not activated for this template. +You can run the [latex template generator] to enable the features. -```bash -npx -p yo -p generator-latex-template -c 'yo latex-template --documentclass=scientific-thesis --latexcompiler=both --overleaf=true --texlive=2026 --enquotes=csquotes --tweakouterquote=babel --todo=pdfcomment --examples=true --howtotext=true --uml=plantuml --docker=dante' -``` +Congratulations. You chose to use all available features. -Use `--uml=mermaid` for Mermaid. -The generator asks for the remaining options (institution, language, and package for source code), which distinguish the `main*.tex` files of this template. +## Tool hints + +### Prerequisites + +- Windows: Recent [MiKTeX](http://miktex.org/). MiKTeX installation hints are given at . +- Mac OS X: Recent [TeX Live](https://www.tug.org/texlive/) (e.g. through [MacTeX](https://tug.org/mactex/)) - Try `sudo tlmgr update --all` if you encounter issues with biblatex +- Linux: Recent TeX Live distribution + +See for refined installation instructions. + +### Usage of `minted` + +To have minted running properly, you have to do following steps on Windows: + +1. Install python: `choco install python` - that uses [chocolatey](https://chocolatey.org/) to install Python +2. Install [latexminted]: `pip instal latexminted` - that uses the Python package manager to install the minted library +3. When latexing, use `-shell-escape`: `pdflatex -shell-escape main-english`. + You can also just execute `latexmk main-english`. ### VS Code configuration @@ -246,26 +166,49 @@ Currently, following extensions are recommended: - [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) to support LaTeX in VS Code and - [LaTeX Utilities](https://marketplace.visualstudio.com/items?itemName=tecosaur.latex-utilities) to enhance LaTeX Workshop - [LTeX+] to have a nice spell checker that also identifies grammar issues -- [JabRef 4 VSCode](https://marketplace.visualstudio.com/items?itemName=jabref.jabref-4-vscode) to use the language server and further features of [JabRef] in VS Code -With the settings below, LaTeX Workshop compiles with the recipe "lualatex ➞ biber ➞ lualatex × 2". -To compile in the Docker container (see ["Docker-based (recommended)"](#docker-based-recommended)), add the following lines to VS Code's `settings.json` (Shift+Ctrl+P, then "Preferences: Open Settings (JSON)"): +Then, change the setting of LaTeX Workshop to use `biber`: + +Press Shift+Ctrl+P to open the command palette. +Then type "JSON" and select "Preferences: Open Settings (JSON)" to open `settings.json`. + +Update the following lines in VS Code's `settings.json` to contain: ```javascript - "latex-workshop.docker.enabled": true, - "latex-workshop.docker.image.latex": "registry.gitlab.com/islandoftex/images/texlive:latest", + "latex-workshop.latex.recipes": [ + { + "name": "lualatex ➞ biblatex ➞ lualatex × 2 🔃", + "tools": [ + "lualatex", + "biblatex", + "lualatex", + "lualatex" + ] + }, + ], + "latex-workshop.latex.tools": [ + // ... + { + "name": "biblatex", + "command": "biblatex", + "args": [ + "%DOCFILE%" + ], + "env": {} + }, + // ... + ], ``` The following settings are additionally recommended: ```javascript { - "editor.wordWrap": "on", // enable soft line breaks - "latex-workshop.view.pdf.viewer": "tab", // display the generated PDF in a separate tab - "latex-workshop.view.pdf.color.light.backgroundColor": "#cccccc", // light theme: use a darker background in the PDF viewer to lift the pages off it - "latex-workshop.view.pdf.color.dark.backgroundColor": "#121314", // dark theme: same, with a dark gray matching the editor - "latex-workshop.latex.autoBuild.run": "never", // never automatically build; alternative: "onSave" (on saving .tex files) - "editor.renderWhitespace": "all", // display all whitespaces + "editor.wordWrap": "on", // enable soft line breaks + "latex-workshop.view.pdf.viewer": "tab", // display the generaded PDF in a separate tab + "latex-workshop.view.pdf.backgroundColor": "#cccccc", // use a darker background in de PDF viewer to lift of the pages from it + "latex-workshop.latex.autoBuild.run": "never", // never automatically build; alternative: "onSave" (on saving .tex files) + "editor.renderWhitespace": "all", // display all whitespaces } ``` @@ -273,70 +216,65 @@ Alternatively, just copy and paste the contents of the [vscode.settings.json](vs You can manually trigger compilation by hitting the green button in the extension or using other methods provided by LaTeX Workshop. +Please remove the magic comments (`% !TeX program ...`) at the top of the `main-english.tex` file. +Although [LaTeX-Workshop supports magic comments](https://github.com/James-Yu/LaTeX-Workshop/blob/master/README.md#magic-comments), it currently does not work reliably. +Without the magic comments, compilation works. + ### LTeX+ tips and tricks [LTeX+] is an offline grammar and spell checker with support for LaTeX and Markdown. -The main file starts with a magic comment that tells LTeX+ the language of the document, e.g., `% LTeX: language=en-US`. -Add the same comment to further `.tex` files. - -## FAQs +Add a magic comment to your files to tell LTeX+ which language to use: -### Q: How do I find the cause of a LaTeX error? +```latex +% LTeX: language=de-DE +``` -In case something goes wrong, you can instruct the LaTeX compiler to stop at the first error: +If you want to use different languages in the text, use the `\foreignlanguage{language}{text}` command. +LTeX+ will detect these elements and automatically switch the spell checker's language. +For example: -```bash -lualatex --synctex=1 main-english +```latex +\foreignlanguage{english}{Therefore, our proposed approach will change the world.} ``` -Run `biber main-english` to get the bibliography rendered (execute `lualatex` afterwards). - -### Q: I get `! Package minted Error: minted v3+ executable is not installed` +## Usage with docker -The complete output reads: +The generated `Dockerfile` is based on the [Dockerfile by the Island of TeX](https://gitlab.com/islandoftex/images/texlive#tex-live-docker-image). -```text -! Package minted Error: minted v3+ executable is not installed, is not added to - PATH, or is not permitted with restricted shell escape; or MiKTeX is being use -d with -aux-directory or -output-directory without setting a TEXMF_OUTPUT_DIREC -TORY environment variable. +```cmd +docker run --rm -v "c:\users\example\latex-document:/workdir" ltg latexmk ``` -The [minted] package needs Python and the Python package [latexminted]. -The Docker image and Overleaf contain both. -For a local installation: +Following one-time setup is required: -1. Install Python, e.g., `choco install python` on Windows. -2. Install or repair [latexminted]: `python -m pip install --force-reinstall latexminted` (see [minted#425](https://github.com/gpoore/minted/issues/425)). +```cmd +docker build -t ltg . +``` -Without Python, use the `*-basic-listings*.tex` variant: it typesets source code with the [listings] package. +## Contained Directories and Files -### Q: How do I spell check a passage in another language? +### Directories -Use the `\foreignlanguage{language}{text}` command. -LTeX+ will detect these elements and automatically switch the spell checker's language. -For example: +- [figures](graphics/) Directory containing the figures. + By using LuaLaTex/PDFLaTeX it is possible to use PDFs, JPGs, PNGs, ... We recommend to use PDFs to enable smooth scaling. -```latex -\foreignlanguage{english}{Therefore, our proposed approach will change the world.} -``` +### Files -### Q: How do I add a word (e.g., the name of a tool) to the spell checkers? +- `main-english.tex` - The main `.tex` file loading all LaTeX packages and their configurations. + - Add text here + - Adjust title etc. here +- [bibliography.bib](bibliography.bib) - Bibliography. [biblatex] format. Manage it with [JabRef]. +- [abbreviations.tex](abbreviations.tex) - Acronyms and abbreviations. +- [commands.tex](commands.tex) - Example LaTeX macros. -Each spell checker reads its own word list; add the word as a new line: +Following additional files are included, which do not need to be adapted: -| Spell checker | Word list | -| --- | --- | -| aspell (CI job `spell-check`, `make spellcheck-aspell`) | `.aspell.en.pws` (English), `.aspell.de.pws` (German); below the first line, no hyphenated words | -| [LTeX+] (VS Code) | `.vscode/ltex.dictionary.en-US.txt`, `.vscode/ltex.dictionary.de-DE.txt`; "Add to dictionary" in VS Code writes there | -| TeXtidote (CI job `textidote`, `make spellcheck-textidote`) | `.textidote.dict` | -| [typos](https://github.com/crate-ci/typos) (CI job `typos`) | `.typos.toml`, section `[default.extend-words]`, e.g., `Heros = "Heros"`; only needed if typos reports the word | +- [localSettings.yaml](localSettings.yaml) - Settings for [latexindent](https://ctan.org/pkg/latexindent) +- [Makefile](Makefile) - The Makefile. Builds on latexmk. +- [Texlivefile](Texlivefile) - List of packages required for a minimal TeXLive installation. -The word lists of aspell, LTeX+, and TeXtidote contain the same words. -Instead of editing each of them, add the word to the aspell or the LTeX+ word list and run `make dictionaries`: it merges both and writes the word into all of them (hyphenated words not into aspell's). -On GitHub, the workflow `Dictionaries` does this after each push that changes one of these word lists and commits the result. -To remove a word, delete it from the aspell and the LTeX+ word list and run `make dictionaries`. +## FAQs ### Q: How can I synchronize updates from the template to my repository? @@ -373,6 +311,32 @@ Alternatively, execute `make format`. See "How can I reformat my `.tex` files?" +### Q: I want to use minted, because I think its syntax highlighting seems to be better. + +You can re-generate the template and choose `minted` as listings environment. +Moreover, ensure that python and [latexminted] are installed properly: + +- `choco install python` +- `pip install latexminted` + +### Q: I have troubles with minted on Windows. + +For instance, on gets following output: + +```text +! Package minted Error: minted v3+ executable is not installed, is not added to + PATH, or is not permitted with restricted shell escape; or MiKTeX is being use +d with -aux-directory or -output-directory without setting a TEXMF_OUTPUT_DIREC +TORY environment variable. +``` + +Try out following command to update `latexminted`. +See [minted#425](https://github.com/gpoore/minted/issues/425) for details. + +```shell +python3 -m pip install --force-reinstall latexminted +``` + ### Q: Can I also write in German? Yes. You can regenerate the template and choose "German" as language. @@ -396,8 +360,9 @@ Install the package `dehyph-exptl`. ### Q: I get ``! I can't find file `clmr28t10+20'.`` -`latexmk` runs `latex`, which produces a DVI file (and not a PDF file), because it does not find its configuration. -Make sure that `.latexmkrc` is in the directory of the document. +You seem to use `latexmk` locally. +Please move `_latexmkrc` to `latexmkrc` to get `latexmk` working. +If you don't do this, `latexmk` tries to execute `latex`, which tries to produce a DVI file (and not a PDF file). ### Q: I get `Font "LatinModernMath-Regular" not found.`. What can I do? @@ -449,6 +414,13 @@ See installation hints of how to update them at different systems. Use the [MiKTeX console](https://miktex.org/howto/miktex-console) to refresh the package index. Then, automatic installation should work again. +### Q: I cannot get minted to run. There is this `-shell-escape` warning. + +Please ensure that your compilation command includes `-shell-escape`. +E.g., `lualatex -shell-escape -synctex=1 main-minted-german.tex`. +When compiling `main-minted-german.tex` with TeXStudio, you will see a dialog warning about overriding the compilation command. +Just answer "(a) allow for this document" and it will work. + ### Q: How to include Excel charts properly? 1. Select the Excel chart you want to use. @@ -475,14 +447,17 @@ We are collecting alternatives at the issue [#25](https://github.com/latextempla - Search the PDF for "TODO" or similar things. Remove `\usepackage{todonotes}` in your main `.tex` file. - Ensure that you run `lualatex` at least three times and that there are no "undefined references". - The margins are intended for good screen reading. **Do not change them** (or do exactly know what you are doing). +### Q: `main-minted-german.tex` does not compile: ``File `main-minted-german-plantuml.latex' not found. \end{plantuml}``. What can I do? + +You did not setup the [plantuml package](https://www.ctan.org/pkg/plantuml) correctly. +Please head to for installation instructions. ## Further information -- Why the templates use which packages: [decision records of the template generator](https://github.com/latextemplates/generator-latex-template/tree/main/docs/decisions) - Other templates: - For German users, go to . - Frank Mittelbach with Ulrike Fischer: [The LaTeX Companion](https://www.latex-project.org/news/2023/03/17/TLC3/) is the ultimate guide for LaTeX: The authors went through all packages offered by [CTAN](https://ctan.org/), selected the most promising ones, described them, and provide minimal working example for each of it. -- Lutz Hering, Heike Hering: [How to Write Technical Reports](https://doi.org/10.1007/978-3-540-69929-3), Springer, 2010; also available in German [Technische Berichte - verständlich gliedern, gut gestalten, überzeugend vortragen](https://doi.org/10.1007/978-3-8348-8317-9). - Highly recommended, because it guides through all aspects of a report (such as a Master Thesis). +- Lutz Hering, Heike Hering: [How to Write Technial Reports](https://doi.org/10.1007/978-3-540-69929-3), Springer, 2010; also available in German [Technische Berichte - verständlich gliedern, gut gestalten, überzeugend vortragen](https://doi.org/10.1007/978-3-8348-8317-9). - Highly recommended, because it guides through all aspects of a report (such as a Master Thesis). - Marcus Deininger et al.: [Studienarbeiten - Ein Leitfaden zur Erstellung, Durchführung und Präsentation wissenschaftlicher Abschlussarbeiten am Beispiel Informatik](https://vdf.ch/studienarbeiten.html?author_id=2877), vdf. - Recommended as guideline for planning and working on the whole thesis. - Charles Lipson, [Cite Right, Second Edition: A Quick Guide to Citation Styles--MLA, APA, Chicago, the Sciences, Professions, and More](http://www.press.uchicago.edu/ucp/books/book/chicago/C/bo10702043.html), Chicago Guides to Writing, Editing, and Publishing, 2011. - Recommended in case you are unsure about how to correctly cite something. @@ -491,13 +466,6 @@ We are collecting alternatives at the issue [#25](https://github.com/latextempla The license of this work is [0BSD](https://spdx.org/licenses/0BSD.html) which corresponds to "public domain". Any derived work can freely be relicensed and can omit original copyright and license information. -### Exceptions - -The logos are trademarks of the universities: use them only on the title page of a thesis submitted there, so that the thesis is not mistaken for a publication of the university. - -- `figures/uhh-logo.pdf` is the logo of the Universität Hamburg, converted from [UHH Universität Hamburg Logo mit Schrift 2010 Farbe CMYK.svg](https://commons.wikimedia.org/wiki/File:UHH_Universit%C3%A4t_Hamburg_Logo_mit_Schrift_2010_Farbe_CMYK.svg) (public domain, via Wikimedia Commons). -- `figures/thu-logo.png` is [THU Logo Subline deutsch RGB.png](https://commons.wikimedia.org/wiki/File:THU_Logo_Subline_deutsch_RGB.png) by Hochschule Ulm, licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/), via Wikimedia Commons. - [biber]: https://www.ctan.org/pkg/biber [biblatex]: http://tex.stackexchange.com/tags/biblatex/info [bibtex]: https://www.ctan.org/pkg/bibtex @@ -512,11 +480,13 @@ The logos are trademarks of the universities: use them only on the title page of [lualatex]: http://www.luatex.org/ [microtype]: https://ctan.org/pkg/microtype [minted]: https://ctan.org/pkg/minted +[natbib]: https://ctan.org/pkg/natbib [paralist]: https://www.ctan.org/pkg/paralist [pdfcomment]: https://www.ctan.org/pkg/pdfcomment [upquote]: https://www.ctan.org/pkg/upquote [JabRef]: https://www.jabref.org +[LanguageTool]: https://languagetool.org/ [latex template generator]: https://www.npmjs.com/package/generator-latex-template [LTeX+]: https://marketplace.visualstudio.com/items?itemName=ltex-plus.vscode-ltex-plus [latexminted]: https://pypi.org/project/latexminted/ diff --git a/Texlivefile b/Texlivefile index 36f1db9a..59c9dd59 100644 --- a/Texlivefile +++ b/Texlivefile @@ -41,7 +41,6 @@ datetime2-german dehyph-exptl diagbox embedfile -authorarchive enumitem environ epstopdf @@ -66,7 +65,6 @@ glossaries-extra glossaries-german graphics helvetic -hologo hycolor hypcap hyperref @@ -94,12 +92,9 @@ lineno lipsum listings lscapeenhanced -ltmermaid ltxcmds luacode lualatex-math -luamplib -metapost luatex85 luatexbase luaxml @@ -112,7 +107,6 @@ fancyvrb verse mathdesign mathtools -metauml mfirstuc microtype mindflow @@ -131,7 +125,6 @@ nfssext-cfr nowidow ntheorem paralist -pdfcol pdfcomment pdfescape pdflscape @@ -139,7 +132,6 @@ pdfpages pdftexcmds pgf pgfplots -pgf-umlsd pict2e placeins plantuml diff --git a/_latexmkrc b/_latexmkrc new file mode 100644 index 00000000..b758ff02 --- /dev/null +++ b/_latexmkrc @@ -0,0 +1,54 @@ +$pdflatex = 'lualatex --shell-escape --file-line-error --synctex=-1 %O %S'; + +#------------------------------------------------------------------------------# +# compilation + +# automatically call lualatex/pdflatex (instead of latex) +$pdf_mode = 1; + +# replaces main.pdf by jobname.pdf +# Note: -pvc may then not find the PDF. +#$jobname = 'thesis'; + +#------------------------------------------------------------------------------# +# preview +# You may put these settings in ~/.latexmkrc instead. + +# >0 <-> equivalent to -pv +$preview_mode = 0; +# >0 <-> equivalent to -pvc +#$preview_continuous_mode = 1; + +if ($^O eq 'MSWin32') { + # Use SumatraPDF instead of the default PDF viewer; it reloads the PDF automatically + $pdf_previewer = 'start "C:\Program Files\SumatraPDF\SumatraPDF.exe"'; +} +# 'evince' is 'Document Viewer' (GNOME's default) +#$pdf_previewer = 'evince'; + +#------------------------------------------------------------------------------# +# bibliography and glossaries + +# enable deletion of *.bbl when calling "latexmk -c" +$bibtex_use = 2; + +# Glossaries inclusion inspired by https://tex.stackexchange.com/a/44316/9075 +add_cus_dep('glo', 'gls', 0, 'run_makeglossaries'); +add_cus_dep('acn', 'acr', 0, 'run_makeglossaries'); + +sub run_makeglossaries { + if ( $silent ) { + # we use -lite to avoid an installation of perl + system "makeglossaries-lite", "-q", $_[0]; + } + else { + system "makeglossaries-lite", $_[0]; + }; +} + +#------------------------------------------------------------------------------# +# cleanup + +# remove more files than in the default configuration +@generated_exts = qw(acn acr alg aux code fls glg glo glo-abr gls glsdefs idx ind ist lof lol lot out run.xml synctex thm toc tpt upa upb wrt); +$clean_ext .= ' %R.ist %R.xdy'; diff --git a/docs/latex-setup.md b/docs/latex-setup.md index 43c68ab1..d178017b 100644 --- a/docs/latex-setup.md +++ b/docs/latex-setup.md @@ -1,118 +1,54 @@ # Recommended LaTeX environments -## TeXStudio as LaTeX Editor +The recommended setup is **Docker** for compiling and **VS Code** for editing. +Both are described in the main README; this page adds platform-specific installation hints and the TeXstudio alternative. -Grammar and spell checking is available at [TeXstudio]. -Please download [LanguageTool] and [configure TeXstudio to use it](http://wiki.languagetool.org/checking-la-tex-with-languagetool#toc4). -Note that it is enough to point to `languagetool-server.jar`. -![language-tool-configuration](texstudio-configuration-languagetool.png) - -The template is compiled using normal compilation commands. -Your LaTeX environment (such as [TeXStudio]) should take care about the compilation transparently. - -If the document needs `--shell-escape` (for PlantUML or Mermaid diagrams, or for minted with TeX Live 2024), its first lines tell TeXstudio to compile with `--shell-escape`. -Then, TeXstudio warns that the compilation command will be overridden. -Please answer `(a) allow for this document`: - -![allow --shell-escape for this document](texstudio-confirmation-1.png) +## Docker (preferred) -At "Build & View", there will be a question to update to biber. -Please answer `(a) allow for this document`: +The generated `Dockerfile` is based on the [docker image by the Island of TeX](https://gitlab.com/islandoftex/images/texlive#tex-live-docker-image). +This provides a perfectly configured LaTeX distribution with all required tools and works the same on Windows, macOS, and Linux. +See [Usage with docker](../README.md#usage-with-docker) in the main README for the build and run commands. -![allow biber for this document](texstudio-confirmation-2.png) +## VS Code as LaTeX editor -When the "Package Installation" dialog pops up at TeXStudio, choose your username at "The package will be installed for:" and uncheck "Always show this dialog before installing packages." -If you want to include .svg graphics, [inkscape] has to be in your path. +Use [VS Code](https://code.visualstudio.com/) with the [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) extension. +The recommended extensions and the required `settings.json` entries are given at [VS Code configuration](../README.md#vs-code-configuration) in the main README. +You can also copy the contents of [vscode.settings.json](../vscode.settings.json) to your VS Code settings file. -**Attention!** The first compilation will take **at least 30 seconds**, because there will be some LaTeX packages installed. +If you do not want LaTeX Workshop to compile automatically after each change, add the following line to your `settings.json` and trigger the compilation manually: -**If TeXstudio doesn't fit your need, check [the list of all available LaTeX Editors](http://tex.stackexchange.com/questions/339/latex-editors-ides).** +```json +"latex-workshop.latex.autoBuild.run": "never", +``` ## JabRef for managing literature Use [JabRef] to manage your bibliography. -Quick installation using [Chocolatey]: `choco install texstudio languagetool jabref`. +Quick installation using [Chocolatey]: `choco install jabref`. A comparison to other literature management software is available at . -See [LaTeX Editors/IDEs question on TeX.SX](http://tex.stackexchange.com/questions/339/latex-editors-ides) for a complete list of LaTeX editors. - -## LaTeX distribution - -Choose one of the two setups: Docker-based or traditional. - -### Docker-based (recommended) -The [TeX Live docker image by the Island of TeX](https://gitlab.com/islandoftex/images/texlive#tex-live-docker-image) provides a perfectly configured LaTeX distribution with all required tools. -It works the same on Windows, macOS, and Linux and ships `latexmk`, `biber`, `latexindent`, Python, and `latexminted`. -Thus, `minted` works without further setup - also on Windows. +## Installation hints for Windows -1. Install Docker: [Docker Desktop](https://docs.docker.com/desktop/) on Windows and macOS, [Docker Engine](https://docs.docker.com/engine/install/) on Linux. - On Linux, follow the [post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/) to run `docker` without `sudo`. -1. Execute `docker pull registry.gitlab.com/islandoftex/images/texlive:latest`. - This downloads approx. 3 GB. -1. Compile on the command line: open a terminal in the directory of your document and run the command for your system. - Replace `main-english` by the main file you use. - - Windows (PowerShell): - - ```powershell - docker run --rm -v "${PWD}:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest latexmk main-english - ``` - - Windows (Command Prompt): - - ```cmd - docker run --rm -v "%cd%:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest latexmk main-english - ``` - - Linux and macOS: - - ```shell - docker run --rm -v "$PWD:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest latexmk main-english - ``` - -1. To compile from [TeXstudio], open Options > Configure TeXstudio > Commands and set - - "PdfLaTeX" to `docker run --rm -v "DIROFTEXDOCUMENT:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest pdflatex --shell-escape -synctex=1 -interaction=nonstopmode %.tex`, - - "LuaLaTeX" to `docker run --rm -v "DIROFTEXDOCUMENT:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest lualatex --shell-escape -synctex=1 -interaction=nonstopmode %.tex`, and - - "Biber" to `docker run --rm -v "DIROFTEXDOCUMENT:/workdir" registry.gitlab.com/islandoftex/images/texlive:latest biber %`. - - On Linux and macOS, you can mount the directory at the same path instead (`-v DIROFTEXDOCUMENT:DIROFTEXDOCUMENT --workdir=DIROFTEXDOCUMENT`). - Then, the paths in the generated SyncTeX file match your machine, and jumping between source and PDF keeps working. -1. Press "Compile" (F6) in TeXstudio. - -For VS Code, see ["Using VSCode to Edit, Compile, and Preview PDFs"](#using-vscode-to-edit-compile-and-preview-pdfs). - -### Traditional - -Install a LaTeX distribution on your machine: [MiKTeX](https://miktex.org/download) on Windows, [TeX Live](https://www.tug.org/texlive/) on macOS and Linux. - -#### Installation hints for Ubuntu - -- From Ubuntu 18.10 onwards, the basic version of the template works without issues. - Advanced usages such as cool syntax highlighting with [minted](https://www.ctan.org/pkg/minted) needs more configuration. -- Ubuntu 16.04 [ships biber 2.4](https://bugs.launchpad.net/ubuntu/+source/biber/+bug/1589644), so you have to upgrade your texlive distribution. - The easiest way is to uninstall the ubuntu package and use [install-tl-ubuntu](https://github.com/scottkosty/install-tl-ubuntu). - Then, you can follow the instructions given at to update your texlive distribution. - If you do not want to have an updated installation, but fiddle around with dirty patching your installation, please follow . - -#### Installation hints for Windows +If you prefer a local LaTeX installation over Docker, use [MiKTeX](http://miktex.org/). Note: The default installation of MiKTeX might ship with incompatible biblatex and biber packages. **You have to keep your MiKTeX up to date.** In case you followed the linked installation steps, you only have to run "Update MiKTeX". If you installed MiKTeX other ways, you have to run "Update MiKTeX (Admin)" and "Update MiKTeX" and check in both tools for updates (see ). -##### Preparations +### Preparations 1. Install [chocolatey]: 1. Open `cmd.exe` as Administrator 2. Paste and hit Enter `@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -InputFormat None -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://chocolatey.org/install.ps1'))" && SET "PATH=%PATH%;%ALLUSERSPROFILE%\chocolatey\bin"` 1. Execute `choco feature enable -n=allowGlobalConfirmation` to get rid off additional installation confirmations. -1. Execute `choco install texstudio sumatrapdf.install strawberryperl jre8 jabref languagetool` to install necessary tooling. +1. Execute `choco install vscode sumatrapdf.install strawberryperl jre8 jabref languagetool` to install necessary tooling. + Replace `vscode` by `texstudio` if you prefer TeXstudio. 1. In case [PlantUML](http://plantuml.com/) should be used, follow the installation instructions at listed at the "pre-conditions" section. 1. For more recommended tooling see . -##### Recommended setup of MiKTeX +### Recommended setup of MiKTeX 1. Download the basic installer from 1. Start it @@ -143,71 +79,63 @@ If you installed MiKTeX other ways, you have to run "Update MiKTeX (Admin)" and 8. Execute `initexmf --update-fndb` (ensure that no other MiKTeX tooling such as the [MiKTeX Console](https://miktex.org/howto/miktex-console) is run in parallel - see ) 9. Execute `initexmf --mklinks --force` -## Using VSCode to Edit, Compile, and Preview PDFs - -***Note: The configuration of LaTeX Workshop on [Fast Guide on Writing LaTeX with LaTeX Workshop in VS Code](https://mathjiajia.github.io/vscode-and-latex/) may require some modifications to work with this template.*** - -### Prerequisites - -1. Install [VSCode](https://code.visualstudio.com/). -2. Install [LaTeX Workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop). -3. Install a LaTeX distribution (see ["LaTeX distribution"](#latex-distribution)). - With the Docker-based setup, LaTeX Workshop can run the tools in the container (an experimental feature of LaTeX Workshop); add the following to `settings.json`: - - ```json - "latex-workshop.docker.enabled": true, - "latex-workshop.docker.image.latex": "registry.gitlab.com/islandoftex/images/texlive:latest", - ``` - -### Recommended Setup of VSCode - -1. Open VSCode. -2. Press Shift+Ctrl+P to open the command palette. Then type "JSON" and select "Preferences: Open Settings (JSON)" to open `settings.json`. -3. Now copy and paste the following snippet into your `settings.json` file (inside the brackets `{}` of your file). - - ```json - "latex-workshop.latex.tools": [ - { - "name": "pdflatex", - "command": "pdflatex", - "args": [ - "-synctex=1", - "-interaction=nonstopmode", - "-file-line-error", - "%DOC%" - ], - "env": {} - }, - { - "name": "biber", - "command": "biber", - "args": [ - "%DOCFILE%" - ], - "env": {} - } - ], - - "latex-workshop.latex.recipes": [ - { - "name": "pdflatex ➞ biber ➞ pdflatexX2", - "tools": [ - "pdflatex", - "biber", - "pdflatex", - "pdflatex" - ] - } - ], - ``` - -4. (optional) If you add the following line into your `settings.json`, the LaTeX Workshop extension will not automatically compile the code after any changes. You can manually trigger compilation by hitting the green button in the extension or using other methods provided by LaTeX Workshop. - - ```json - "latex-workshop.latex.autoBuild.run": "never", - ``` +## Installation hints for Ubuntu + +- From Ubuntu 18.10 onwards, the basic version of the template works without issues. + Advanced usages such as cool syntax highlighting with [minted](https://www.ctan.org/pkg/minted) needs more configuration. +- Ubuntu 16.04 [ships biber 2.4](https://bugs.launchpad.net/ubuntu/+source/biber/+bug/1589644), so you have to upgrade your texlive distribution. + The easiest way is to uninstall the ubuntu package and use [install-tl-ubuntu](https://github.com/scottkosty/install-tl-ubuntu). + Then, you can follow the instructions given at to update your texlive distribution. + If you do not want to have an updated installation, but fiddle around with dirty patching your installation, please follow . + +Always working solution: Use [Docker](#docker-preferred). + +## TeXstudio as LaTeX editor (alternative) + +If VS Code does not fit your needs, [TeXstudio] is a good alternative. +Windows: `choco install texstudio languagetool`. +For a complete list of LaTeX editors, see [the LaTeX Editors/IDEs question on TeX.SX](http://tex.stackexchange.com/questions/339/latex-editors-ides). + +Grammar and spell checking is available at [TeXstudio]. +Please download [LanguageTool] and [configure TeXstudio to use it](http://wiki.languagetool.org/checking-la-tex-with-languagetool#toc4). +Note that it is enough to point to `languagetool-server.jar`. +![language-tool-configuration](texstudio-configuration-languagetool.png) + +The template is compiled using normal compilation commands. +Your LaTeX environment (such as [TeXstudio]) should take care about the compilation transparently. + +If you open `main-minted-german.tex`, there will be a warning that the compilation command will be overridden. +Please answer `(a) allow for this document`: + +![allow --shell-escape for this document](texstudio-confirmation-1.png) + +At "Build & View", there will be a question to update to biber. +Please answer `(a) allow for this document`: + +![allow biber for this document](texstudio-confirmation-2.png) + +When the "Package Installation" dialog pops up at TeXstudio, choose your username at "The package will be installed for:" and uncheck "Always show this dialog before installing packages." +If you want to include .svg graphics, [inkscape] has to be in your path. + +**Attention!** The first compilation will take **at least 30 seconds**, because there will be some LaTeX packages installed. + +### Using TeXstudio with the Docker image + +1. Execute `sudo visudo` to edit the sudoers file +1. Add the line `myusername ALL = (root) NOPASSWD: /usr/bin/docker`. Replace `myusername` accordingly. (Source: ) +1. Execute `sudo docker pull registry.gitlab.com/islandoftex/images/texlive:latest`. + This should not ask for any password. + Will download approx. 4GB. +1. Open TeXstudio +1. Options > Configure TeXstudio > Commands +1. Set "PdfLaTeX" to `docker run --rm -v DIROFTEXDOCUMENT:DIROFTEXDOCUMENT --workdir=DIROFTEXDOCUMENT registry.gitlab.com/islandoftex/images/texlive:latest pdflatex --shell-escape -synctex=1 -interaction=nonstopmode %.tex`, replace `DIROFTEXDOCUMENT` by the directory of your latex document. Example: `/home/user/thesis`. +1. Set "LuaLaTeX" to `docker run --rm -v DIROFTEXDOCUMENT:DIROFTEXDOCUMENT --workdir=DIROFTEXDOCUMENT registry.gitlab.com/islandoftex/images/texlive:latest lualatex --shell-escape -synctex=1 -interaction=nonstopmode %.tex`, replace `DIROFTEXDOCUMENT` by the directory of your latex document. Example: `/home/user/thesis`. +1. Set "Biber" to `docker run --rm -v DIROFTEXDOCUMENT:DIROFTEXDOCUMENT --workdir=DIROFTEXDOCUMENT registry.gitlab.com/islandoftex/images/texlive:latest biber %`, replace `DIROFTEXDOCUMENT` by the directory of your latex document. Example: `/home/user/thesis`. +1. Check if the "docker pull" command from step 3 succeed. If not, wait. +1. Try to press the "Compile" (F6) button in TeXstudio. [chocolatey]: https://chocolatey.org/ +[inkscape]: https://inkscape.org/ [JabRef]: https://www.jabref.org [LanguageTool]: https://languagetool.org/ -[TeXstudio]: http://texstudio.sourceforge.net/ +[TeXstudio]: https://www.texstudio.org/ diff --git a/docs/thesis-checklist.md b/docs/thesis-checklist.md index 08e686da..46ef73cc 100644 --- a/docs/thesis-checklist.md +++ b/docs/thesis-checklist.md @@ -46,6 +46,6 @@ A reader who opens the thesis anywhere and has ten minutes must find their way. - [ ] The PDF shows no `??` (undefined references or citations). - [ ] All TODO notes are resolved. - [ ] All hints and examples of this template are removed. -- [ ] The text is spell-checked and grammar-checked, e.g., with LTeX+ in your editor or with `make spellcheck` (see the README). +- [ ] The text is spell-checked and grammar-checked (see the README for tools). - [ ] The title page is correct: title, your name, supervisors, dates. - [ ] The formal requirements of your examination office are met (page limit, signed declaration, number of copies, file format). diff --git a/localSettings.yaml b/localSettings.yaml index 3fd3c681..a2ad9934 100644 --- a/localSettings.yaml +++ b/localSettings.yaml @@ -54,13 +54,9 @@ verbatimCommands: # documentation: https://latexindentpl.readthedocs.io/en/latest/sec-default-user-local.html#verbatim-code-blocks verbatimEnvironments: lstlisting: 1 - luacode: 1 - luacode*: 1 markdown: 1 - mermaid: 1 mindflow: 1 minted: 1 - plantuml: 1 verbatim: 1 # TODO: algorithm configuration - see https://latexindentpl.readthedocs.io/en/latest/sec-default-user-local.html#lst-special2-mod1 diff --git a/main-english-thu.tex b/main-english-thu.tex index 939c4fde..78e7fc5d 100644 --- a/main-english-thu.tex +++ b/main-english-thu.tex @@ -2,22 +2,19 @@ % LTeX: language=en-US % !TeX encoding = utf8 % !TeX program = lualatex +% !TeX TXS-program:compile = txs:///lualatex/[--shell-escape] % !BIB program = biber % -*- coding:utf-8 mod:LaTeX -*- -% -% vvvvvvvv The content starts in line 958 (\begin{document}); the first -% chapter (\include{chapters-en/10 - introduction}) is included in line 1094. -% The chapters are in the directory "chapters-en". -% Everything above is the preamble: document class, packages, and settings. +% The following package allows \\ at the title page +% For more information see https://github.com/latextemplates/scientific-thesis-cover/issues/4 +\RequirePackage{kvoptions-patch} \documentclass[ % fontsize=11pt is the standard numbers=noenddot, english, % English as main language; this parameter is passed to other packages (e.g., selnolig in the case of lualatex) a4paper, % KOMAScript allows for both paper=a4 and (standard) a4paper - https://tex.stackexchange.com/a/61044/9075 - twoside=false, % optimized for reading on screen: the same margins on every page and no blank pages - open=any, % a chapter starts on the next page, not necessarily on a right-hand one - % For two-sided printing, replace the two lines above by "twoside, open=right," + twoside, % We are optimizing for both screen and two-sided printing. So the page numbers will jump, but the content is configured to stay in the middle (by using the geometry package) bibliography=totoc, % idxtotoc, % Index ins Inhaltsverzeichnis % liststotoc, % List of * ins Inhaltsverzeichnis, mit liststotocnumbered werden die Abbildungsverzeichnisse nummeriert @@ -130,7 +127,7 @@ %% !!! If you change the font, be sure that words such as "workflow" can %% !!! still be copied from the PDF. If this is not the case, you have -%% !!! to use glyphtounicode (pdflatex only). See the comment at \input{glyphtounicode}. +%% !!! to use glyphtounicode. See comment at cmap package. %% %% Background: "workflow" contains "fl" which is a ligature, which in turn %% is rendered as one character in the PDF and needs to be split @@ -150,7 +147,7 @@ Ligatures=TeX ] % See https://tug.org/FontCatalogue/texgyreheros/ for more information - \setsansfont[Scale=.9]{TeX Gyre Heros} + \setsansfont[Scale=.9]{TeX Gyre Heros Regular} % shapely l, upright quotes % Normal scaling is too large --> thus, we use ",Scale=.9" \ifwindows @@ -159,8 +156,9 @@ \setmonofont[StylisticSet={1,3},Scale=.9]{Inconsolatazi4} \fi - % Enable proper ligatures for English documents (German documents use autotype, see ADR-0008) + % Enable proper ligatures % For more information see https://ctan.org/pkg/selnolig + % language "english" or "ngerman" is passed to selnolig by the document class \usepackage{selnolig} \else @@ -180,7 +178,7 @@ % Fallback font - if the subsequent font packages do not define a font (e.g., monospaced) % This is the modern package for "Computer Modern". -% In case this gets activated, check that ligatures can still be copied (pdflatex: glyphtounicode) +% In case this gets activated, one has to switch from cmap package to glyphtounicode (in the case of pdflatex) %\usepackage[% % rm={oldstyle=false,proportional=true},% % sf={oldstyle=false,proportional=true},% @@ -232,18 +230,15 @@ %\usepackage{stmaryrd} % for \ovee, \owedge, \otimes %\usepackage{marvosym} % for \Writinghand %patched to not redefine \Rightarrow %\usepackage{mathrsfs} % nice cursive letters via \mathscr{} -%\usepackage{calrsfs} %\mathcal{} with slightly bolder letters - does not look that good. +%\usepackage{calrsfs} %\mathcal{} ein bisserl dickeren buchstaben erzeugen - sieht net so gut aus. -% Header: the chapter on the left, the current section on the right. -% autooneside=false keeps the section mark in a single-sided document. -\KOMAoptions{autooneside=false} \automark[section]{chapter} \setkomafont{pageheadfoot}{\normalfont\sffamily} \setkomafont{pagenumber}{\normalfont\sffamily} -\ihead[]{\leftmark} +\ihead[]{} \chead[]{} -\ohead[]{\rightmark} +\ohead[]{\headmark} \cfoot[]{} \ofoot[\usekomafont{pagenumber}\thepage]{\usekomafont{pagenumber}\thepage} \ifoot[]{} @@ -292,8 +287,6 @@ \fi \usepackage[dvipsnames, table]{xcolor} - -\definecolor{thublue}{RGB}{0,84,163} % See https://github.com/gpoore/minted \usepackage[newfloat]{minted} @@ -320,7 +313,8 @@ %\usemintedstyle{rrt} %\usemintedstyle{borland} -% caption provides \captionof{listing} (used for listings spanning multiple pages) and sets the label in bold +% We need to load caption to have a bold font on the label +% The other parameters mimic the layout of the LNCS class \usepackage[labelfont=bf,font=small,skip=4pt]{caption} \SetupFloatingEnvironment{listing}{name=List.,within=none} @@ -330,20 +324,9 @@ % \AtBeginEnvironment{listing}{\setcounter{listing}{\value{lstlisting}}} % \AtEndEnvironment{listing}{\stepcounter{lstlisting}} -% Enable \label in listing lines (via escapeinside) and referencing them using \zcref, e.g., "Line 2". -% fancyvrb steps the line counter without \refstepcounter: no counter for \zcref and no target for the hyperlink. -% See https://github.com/gusbrs/zref-clever/issues/65 and https://tex.stackexchange.com/q/132420/9075. -\makeatletter -\def\FV@refstepcounter#1{% - \refstepcounter{#1}% - \protected@edef\@currentlabel{\csname p@#1\endcsname\arabic{#1}}% -} -% Unique hyperlink targets in each listing -\newcounter{FancyVerbListing} -\let\FV@StepLineNo@orig\FV@StepLineNo -\def\FV@StepLineNo{\stepcounter{FancyVerbListing}\FV@StepLineNo@orig} -\def\theHFancyVerbLine{\arabic{FancyVerbListing}.\arabic{FancyVerbLine}} -\makeatother +% Intermediate solution for hyperlinked refs. See https://tex.stackexchange.com/q/132420/9075 for more information. +\newcommand{\labelline}[1]{\label{#1}\hypertarget{#1}{}} +\newcommand{\refline}[1]{\hyperlink{#1}{\FancyVerbLineautorefname~\ref*{#1}}} % For easy quotations: \enquote{text} % This package is very smart when nesting is applied, otherwise textcmds (see below) provides a shorter command @@ -423,45 +406,24 @@ {\multicitedelim} {\usebibmacro{postnote}} -% Link the PDF of a reference ("[PDF]") stored in JabRef's "file" field. -% Only the first file is linked; its path has to be relative to this document. -% Useful if the cited papers are handed in together with the thesis. -% To enable, uncomment the \toggletrue line. -\newtoggle{bibfilelink} -%\toggletrue{bibfilelink} -\DeclareSourcemap{ - \maps[datatype=bibtex]{ - \map{ - % JabRef stores "description:path:type", multiple files separated by ";"; the steps keep the path of the first file - \step[fieldsource=file, match=\regexp{\A[^:;]*:}, replace={}] - \step[fieldsource=file, match=\regexp{:[^:;]*(;.*)?\z}, replace={}] - } - } -} -\DeclareFieldFormat{file}{\href{#1}{[PDF]}} -\renewbibmacro*{finentry}{% - \iftoggle{bibfilelink} - {\iffieldundef{file}{}{\setunit{\addspace}\printfield{file}}} - {}% - \finentry} - -% To embed the bibliography into the PDF (readers can extract it, e.g., with JabRef via "Import into library" on the PDF), uncomment: -%\usepackage{embedfile} -%\embedfile[mimetype=application/x-bibtex,desc=BibTeX entries of all references]{bibliography.bib} +% Embed the bibliography data into the PDF so that readers can extract it +% (e.g., with JabRef via "Import into library" on the PDF) +\usepackage{embedfile} +\embedfile[mimetype=application/x-bibtex,desc=BibTeX entries of all references]{bibliography.bib} -% Colored tables -% -------------- -% xcolor loads the package colortbl +% Farbige Tabellen +% ---------------- +% Das Paket colortbl wird inzwischen automatisch durch xcolor geladen % -% Extended functions within tables -% -------------------------------- +% Erweiterte Funktionen innerhalb von Tabellen +% -------------------------------------------- %%% Doc: http://mirror.ctan.org/tex-archive/macros/latex/contrib/multirow/multirow.sty -\usepackage{multirow} % cells spanning multiple rows +\usepackage{multirow} % Mehrfachspalten % %%% Doc: Documentation inside dtx Package -\usepackage{dcolumn} % alignment at the decimal separator +\usepackage{dcolumn} % Ausrichtung an Komma oder Punkt -% A bit more space between the rows of a table (\extrarowheight is provided by array, which dcolumn loads) +% Etwas mehr Luft zwischen den Tabellenzeilen (\extrarowheight wird von array bereitgestellt, das dcolumn lädt) \setlength{\extrarowheight}{1pt} %%% Doc: http://mirror.ctan.org/tex-archive/macros/latex/contrib/supertabular/supertabular.pdf @@ -475,21 +437,6 @@ % longtable: tables that automatically break across page boundaries. \usepackage{longtable} -% UML diagrams without external tools (see the "UML diagrams" section in the LaTeX hints): -% - MetaUML (class and component diagrams) is MetaPost code, which lualatex runs itself via luamplib -% - pgf-umlsd (sequence diagrams) is TikZ code, which works with every engine -\ifluatex - \usepackage{luamplib} - % Typeset the labels of MetaUML with TeX, i.e., in the fonts of the document - \mplibtextextlabel{enable} - % luamplib calls \tag_mc_reset_box:N also when PDF tagging is off; the LaTeX kernel provides no - % no-op for it (in contrast to the other tagging commands), which leads to "Undefined control sequence" - \ExplSyntaxOn - \cs_if_exist:NF \tag_mc_reset_box:N { \cs_new_protected:Npn \tag_mc_reset_box:N #1 { } } - \ExplSyntaxOff -\fi -\usepackage{pgf-umlsd} - %%% Footnotes/Endnotes =================================================== %%% Doc: http://mirror.ctan.org/tex-archive/macros/latex/contrib/footmisc/footmisc.pdf @@ -548,7 +495,7 @@ % % - \textmarker % - \modified -% - \change - addresses a review comment +% - \change - adresses a review comment % Enable nice comments \usepackage{pdfcomment} @@ -590,42 +537,6 @@ \usepackage[group-minimum-digits=4,per-mode=fraction]{siunitx} -% Write text in Markdown instead of LaTeX: \begin{markdown} ... \end{markdown}, or \markdownInput{chapter.md} for a whole file. -% Doc: https://ctan.org/pkg/markdown -% LuaLaTeX only: under pdfLaTeX, the package needs --shell-escape. -\ifluatex - \usepackage[ - citations, % [@key] citation syntax - hybrid, % pass raw LaTeX through - notes, % [^label] referenced footnotes - inlineNotes, % ^[inline footnote text] - pipeTables, % | a | b | style tables - tableCaptions, % : Caption text below a table - tableAttributes, % {#id} identifier on a table caption - headerAttributes, % {#id} identifier on a heading - relativeReferences, % <#id> to reference an id defined via {#id} (typeset by \zcref, see below) - hashEnumerators, % 1) 2) 3) style enumerators - ]{markdown} - % Markdown's own reference syntax <#id> typesets the bare number (\ref). - % Typeset it with \zcref instead, so that "<#tbl:example> shows" reads "Table 1 shows". - % Other links are rendered as before. - \ExplSyntaxOn - \cs_new_protected:Npn \ltg_markdown_link:nnnn #1#2#3#4 - { - \tl_set:Nx \l_tmpa_tl { \tl_range:nnn {#3} { 1 } { 1 } } - \bool_lazy_all:nTF - { - { \str_if_eq_p:nn {#1} {#2} } - { \str_if_eq_p:VV \l_tmpa_tl \c_hash_str } - { \tl_if_empty_p:n {#4} } - } - { \exp_args:Nx \zcref { \tl_range:nnn {#3} { 2 } { -1 } } } - { \markdownRendererLinkPrototype {#1} {#2} {#3} {#4} } - } - \markdownSetup{ renderers = { link = { \ltg_markdown_link:nnnn {#1} {#2} {#3} {#4} } } } - \ExplSyntaxOff -\fi - % See http://tex.stackexchange.com/a/83051/9075 % Normally, doesn't work with hyperref, but cleveref (or zref-vario) fixes that \usepackage{varioref} @@ -675,7 +586,7 @@ % https://ctan.org/pkg/algorithms % Consists of two environments: algorithm and algorithmic -% Although outdated, it defines the "algorithm" float environment +% Although oudated, it defines the "algorithm" float enviornment % TODO: Define floating environment "algorithm" in other ways \usepackage[chapter]{algorithm} @@ -683,6 +594,8 @@ % Successor of algorithmicx; more modern than https://ctan.org/pkg/algorithms \usepackage{algpseudocodex} +\floatname{algorithm}{Algorithmus} +\renewcommand{\listalgorithmname}{Algorithmenverzeichnis} \newcommand{\commentchar}{\ensuremath{/\mkern-4mu/}} \algrenewcommand{\algorithmiccomment}[1]{\hfill $\commentchar$ #1} @@ -696,57 +609,20 @@ \zcsetup{cap, nameinlink=true} % \Zcref{...} is short for \zcref[S]{...}: capitalized, unabbreviated name at the beginning of a sentence \NewDocumentCommand{\Zcref}{s O{} m}{\IfBooleanTF{#1}{\zcref*[S,#2]{#3}}{\zcref[S,#2]{#3}}} -% Lines of minted listings are referenced as "Line 2" -\zcsetup{countertype={FancyVerbLine=line}} % Page-aware references: \zvref{...} (and \zvref[S]{...}) reads like "Figure 5 on the next page" \usepackage{zref-vario} \zcLanguageSetup{english}{type=page, Name-sg=page, Name-pl=pages} % "on page 5", not "on Page 5" -% Numbered research questions: \defRQ{}{