flukx/latextemplate
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

move technical explanations into technical-readme

Browse source
This commit is contained in:
flukx 2022-08-05 19:53:41 +02:00
parent 6215f31b88
commit 4bc0980fe1
2 changed files with 28 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
README
View file

@ -1,15 +0,0 @@
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 (section), 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/tikz.
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 erstellt in der Präambel (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.
• 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 avaiable as an artifact. Then it is avaiable 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.

28
technical-readme.md Normal file
View file

@ -0,0 +1,28 @@
# 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](https://gitlab.com/flukx/latexwisdom/-/blob/master/tex/unicode.tex).
# 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.