FOP-2425-Projekt-Documentation-TeX

Die $\LaTeX$-Vorlage für die Dokumentation des FOP-Projekts im Wintersemester 2024/2025. Bitte wie bei anderen Abgaben auch den Quellcode der eigenen Abgabe nicht vor der Deadline veröffentlichen. (privates Repository)

Automatisches Setup (empfohlen)

Lokal (Devcontainer)

• Docker installieren
• VS-Code (oder die Open-Source Variante Code-OSS) und Remote-Containers-Extension installieren
• Dieses Repository klonen
• In VS-Code öffnen
• Auf die Meldung "Reopen in Container" klicken
• Falls die Meldung nicht angezeigt werden sollte, kann der Container auch über die Command Palette (F1) geöffnet werden: Remote-Containers: Reopen in Container
• Für dark-mode kompillierung die Environment Variable DARK_MODE=1 unter der Einstellung "latex-workshop.latex.tools" hinzufügen

Lokal (Docker)

• Docker installieren
• Dieses Repository klonen
• kompilieren z.B. mit docker run --rm -v $(pwd):/workspace -w /workspace make -j $(nproc)

Online (Sharelatex der TU-Darmstadt)

Falls eine Latex-Installation nicht möglich ist, haben wir hier auch eine Sharelatex-Vorlage erstellt: Sharelatex

Um diese zu nutzen:

• Einloggen auf Sharelatex
• Den Link zum Template öffnen
• Menu -> Copy Project
• Projektname eingeben und auf "Create" klicken

Manuelle Installation (nicht empfohlen, aufwendig)

• Latex-Installation (z.B. MikTex oder TexLive)
• Installation der TU-Template und der verwendeten Plugins (inklusive Logo!)
• Installation der AlgoTeX-Vorlage

Formatieren

Automatisch mit pre-commit hook

Der Pre-commit Hook formatiert die Dateien automatisch, bevor sie committet werden. Dieser Hook wird auch für die CI verwendet, um sicherzustellen, dass die Dateien immer formatiert sind.

um dem Pre-commit Hook zu verwenden, muss das python package pre-commit installiert werden. (siehe Anleitung von Pre-commit)

pip install pre-commit

Hinweis: Auf manchen Linux-Distributionen, die python-Pakete nicht über pip installieren, sollte das Paket pre-commit bzw. python3-pre-commit über den Paketmanager installiert werden.

Dann kann der Pre-commit Hook mit folgendem Befehl installiert werden:

pre-commit install

Der Pre-commit Hook wird nun bei jedem Commit ausgeführt und formatiert die Dateien automatisch.

Falls der Pre-commit Hook unabhängig von einem Commit ausgeführt werden soll, kann er mit folgendem Befehl manuell ausgeführt werden:

pre-commit run -a

Manuell mit latexindent

Hinweis: Wenn VS-Code verwendet wird (mit oder ohne devcontainer), sollten die korrekten Einstellungen automatisch geladen werden.

Um eine einheitliche Formatierung aller Übungsblätter zu gewährleisten, muss Latexindent installiert und entsprechend konfiguriert werden, um die mitgelieferte latexindent.yaml zu verwenden. Ein Aufruf von latexindent könnte z.B. so aussehen:

latexindent.pl -l -w myfile.tex

in VS-Code mit LaTeX-Workshop kann man die Folgende Konfiguration verwenden:

"latex-workshop.latexindent.args": [
    "-c",
    "%DIR%/",
    "%TMPFILE%",
    "-l=%WORKSPACE_FOLDER%/latexindent.yaml",
    // "-m", // -m can have undesired sideeffects
    "-y=defaultIndent: '%INDENT%'"
],

Alternativ kann die Datei defaultSettings.yaml mit der mitgelieferten latexindent.yaml überschrieben werden. Den Speicherort der Default Settings findet man über:

latexindent -vv

Kompilieren

Automatisch mit IDE (empfohlen)

Die meisten LaTeX-Editoren bieten eine Möglichkeit, das Dokument automatisch zu kompilieren. In VS-Code kann dies z.B. mit der LaTeX-Workshop-Extension erreicht werden.

Automatisch mit make

Das Übungsblatt kann IDE-Unabhängig mit dem Befehl make -j kompiliert werden. Der Parameter -j sorgt dafür, dass die Datei parallel kompiliert wird, was die Kompilierzeit verkürzt. Dabei werdeen die folgenden Versionen erstellt:

• light mode
• dark mode
• light mode ohne sichtbare Punktzahlen (für Reviewer)
• dark mode ohne sichtbare Punktzahlen (für Reviewer)

Automatisch mit act

Falls genau die gleiche Umgebung wie in der CI benötigt wird, kann act verwendet werden. Act nutzt Docker, um die CI-Umgebung lokal zu simulieren. Dann kann der Build mit folgendem Befehl ausgeführt werden:

act -j build --artifact-server-path /tmp/artifacts

Die erstellten PDFs werden dann im Ordner /tmp/artifacts abgelegt. (bei Bedarf kann der Pfad angepasst werden)

Spell checking

Für Spell checking mit VS-Code empfehlen wir LTex, eine entsprehcende Konfiguration ist vorgegeben.

LTex ist standardmäßig auf Deutsch eingestellt. Wenn ein englischer Abschnitt geprüft werden soll, kann die Sprache dafür temporär auf Englisch gestellt werden:

% Deutscher Text
Das ist ein Test
\begin{otherlanguage}{english}
    % Englischer Text
    This is a test.
\end{otherlanguage}

Empfehlungen für LaTeX-Distribution und -Editoren

• Empfohlener Compiler: latexmk mit LuaLaTeX
• Empfohlene LaTeX-Distribution: TeX-Live
• Auflistung der Empfohlenen LaTeX-Editoren:
  • VS-Code (oder die Open-Source Variante Code-OSS) mit LaTeX-Workshop-Extension
  • Neovim mit VimTeX-Plugin
  • IntelliJ Idea mit TeXiFy IDEA-Plugin
  • TeX-Studio
• Hinweise für das Auswählen von PDF-Viewern:
  • Ein guter PDF-Viewer sollte synctex unterstützen, sodass man zwischen Quellcode und PDF hin- und her springen kann