latextemplate/technical-readme.md

LaTeX

Die Hauptdatei (das ganze Dokument) ist üblicherweise in .maindir/tex/main.tex, kann aber auch jede andere tex Datei sein. Es beinhaltet mit einem modifizierten \input-Befehl (\textinput) die verschiedenen Kapitel (chapter) oder Abschnitte (sections), in weitere Dateien ausgelagert. Alle Dateien mit LaTeX-Code liegen in /tex. Wie du sie anordnest, ist dir überlassen. Die tikz-Zeichnungen liegen im Ordner .maindir/graphics.

Man kann jede Datei im Ordner /tex einzeln kompilieren. Dafür sind einige Hürden zu nehmen gewesen:

• Pfade von Dateien, die mit \input eingebunden werden, müssen funktionieren, egal, wo die Datei liegt. Das ist dadurch gelöst, dass alle \input-Anweisungen durch \maininput, \textinput, \tikzinput ersetzt wurden. Diese setzen .maindir/ vor den Pfad. Das ist ein symlink, der in allen Ordnern liegt und jeweils zum Hauptordner referenziert. Diese Links können automatisch erzeugt werden mit dem python-skript .maindir/scripts/maindircreate.py (muss im Hauptordner ausgeführt werden).

• Die Präambel darf nur einmal eingebunden werden. Um dies zu erreichen, fügt keine Datei die Präambel direkt ein (mit input), sondern alle Dateien binden mit \input{.maindir/tex/header/preamble-section} einen Wrapper ein, der die Präambel nur lädt, wenn der Wrapper bisher noch nicht aufgerufen wurde. Dort werden auch die Ersatzbefehle für \begin und \end{document} definiert: \docStart und \docEnd. Damit \docEnd im richtigen Fall das Dokument beendet läuft der counter filedepthScript mit, der anzeigt, in welcher Einfügetiefe wir uns befinden.

• Der Counter filedepthScript wird in der Präambel erstellt (die nur einmal aufgerufen wird), erhöht und verringert beim Aufruf von \maininput (und damit auch bei \textinput und \tikzinput). Im gerade kompilierten "Hauptdokument" ist der Counter auf 0, in allen weiteren auf >0.

• \docStart und \docEnd hätten eigentlich ein environment sein sollen. Dabei gab es aber den Fehler, dass dieses Environment angeblich nicht beendet wurde bevor das Dokument mit \end{document} beendet wurde. Interessanterweise konnte ich den Fehler aber nicht zuverlässig reproduzieren, sondern nur bei Dateien, die keine weiteren eingefügt haben oder irgendeine andere irrelevante Eigenschaft haben.

• Die Datei tex/_TEMPLATE.tex beinhaltet die Dinge, die in jede (Unter-)datei, die auch alleine kompilieren soll, rein muss. Beim erstellen eines neuen Kapitels kopiert man also _TEMPLATE.tex.

• In order to have a clean repo without all the cluttering temporary latex files there exists the .latexmkrc file in the main directory and a symlink to it in the /tex directory. It specifies to put these files into /out, no matter where you are (thanks to .maindir) and to use lualatex.

• lualatex instead of pdflatex is used to allow proper use of Unicode. For details see my LaTeX-wisdom chapter.

CI (automatic compiling)

• If you work with gitlab you can use the CI. For this there is the .gitlab-ci.yml file that tells gitlab to compile the main file and make it available as an artifact. Then it is available under the api link https://your.gitlab.instance.de/api/v4/projects/your-project-id/jobs/artifacts/master/raw/main.pdf?job=compiling You get the project id visible on the main page of your project. master is the branch you want to use for that continous compiling and compiling is the name of the job, specified in the .gitlab-ci.yml. main.pdf is the name of the file generated, specified via the main tex-file name and the .latexmkrc.

markdown-notes

Man möchte vielleicht nicht alle Notizen in komplettem LaTeX machen, sondern markdown verwenden. Das wird, wenn gitlab nicht gerade komische Dinge tut, auch von gitlab im Internet schön angezeigt. Standard-Markdown markiert Matheumgebungen mit $...$. gitlab-Markdown mit $`...`$ (sinnlos, aber nicht vermeidbar.) Um Markdown-Dateien, die man selbst schreibt, automatisch zu reparieren und mit zu versehen, kopiere das Skript .maindir/scripts/pre-commit nach .maindir/.git/hooks. Das kontrolliert dann und fragt beim committen, ob du die Dateien reparieren möchtest. Wenn ja, musst du danach nochmal committen.