Travis CI

Build History

Bachelorarbeit Dokumentation Vorlage

In diesem Repository ist eine LaTeX Vorlage für eine Bachelorarbeit, die Arbeit ist nach der "Vorlage & Formulare\AufbauDokumentation" auf dem SharePoint Ordner I_Projektschiene der HSLU strukturiert. Die einzelnen Kapitel sind in separate TeX-Dateien im Ordner include ausgelagert und werden über den Befehl \include{Datei.tex} in das Hauptdokument eingebunden.

Die Ordnerstruktur ist die folgende:

Hauptordner
	|- appendix				Alle Dokumente für den Anhang (PDFs in diesem Ordner werden durch das .gitignore nicht erfasst)
	|- img					Alle Bilder (werden durch den \graphicspath im Hauptdokument gefunden)
	|- include				Alle Kapitel-Dateien welche in das Hauptdokument eingebunden werden (inklusive Präambel)
	|- web-abstract				Ordner für das Web Abstract
	|- .gitignore
	|- .travis.yml				Konfigurationsdatei für Travis
	|- .version				Hilfsdatei für die Versionierung für das CD über Travis
	|- BA-Dokumentation-Template.tex	Hauptdatei
	|- Referenzen.bib			BibTeX Datei / Referenzbibliothek
	|- texlive.profile			Hilfsdatei für das Installskript
	|_ texlive_install.sh			Installskript

Arbeiten und Kompilieren mit TeXStudio

Ich (Pascal) empfehle euch mit TeXStudio zu arbeiten, Dane eher den TeXMaker (er kann das Layout von TS nicht leiden). Egal welchen Editor ihr verwendet, da wir sowohl ein Glossar wie auch ein verbessertes Bibliotheksbackend (Biber) verwenden, kann man das Dokument nicht einfach mit F5 in TeXStudio bauen.

• pdflatex (Referenzen werden gesammelt)
• Biber (Referenzen werden in einem Bibliotheksfile zusammengefasst)
• makeglossaries (Glossarfile wird erstellt)
• pdflatex (Bibliotheksfile und Glossar werden gesammelt und im Dokument richtig eingebunden und verwiesen)
• pdflatex (Inhaltsverzeichnis wird mit korrekten Seitenzahlen gefüllt)

In TeXStudio könnt ihr euch diesen Befehl über Options>Configure TeXStudio>Build>User Commands einrichten

Über den Rollgabelschlüssel an der rechten Seite den neuen Befehl bearbeiten

Und die jeweiligen Befehle per "Add" dem Command hinzufügen

Ausgeführt wird der Befehl über Tools>User>Jeweiliger UserCommand

Travis CI/CD

Jeder commit wird über Travis gebaut und bei einer Änderung auf dem Master direkt als "Pre-Release" deployed. Dafür muss Travis-CI.org oder Travis-CI.com zuerst die diesbezüglichen Berechtigungen erhalten, und für dieses Repo aktiviert sein. Danach muss der Dateiname in travis.yml nachgetragen werden. Damit das Deployment funktioniert muss ein OAuth Token generiert werden und in Travis hinterlegt werden.

Versionierung

Unsere Versionierung folgt dem Schema v.(Major).(Minor).(Commitnummer - Automatisch), dies aus dem Grund damit die Version sicher immer automatisch inkrementiert wird, und keine identischen Versionsnummern für verschiedene Dokumente existieren können. Major und Minor sind in der Datei .version spezifiziert, während Travis die Buildnummer automatisch einfügt.

Anpassungen in .travis.yml

Ändere den Name von FILE_NAME auf dein Dokument:

env:
  - FILE_NAME=NAME-DEINES-DOKUMENTS

Warum die vielen tlmgr install?

In einer ersten Version installierten wir die ganze TeXLive Suite für jeden Build. Dies hat jeweils um die zehn Minuten gedauert. Im Vergleich dazu lief der Build der Datei jeweils maximal eine Minute. Diese Diskrepanz wollten wir angehen. Daher installieren wir eine minimale Umgebung über das Installierskript texlive_install.sh. Damit aber unser Build nicht failt, müssen wir alle fehlenden Packete (und deren Abhängigkeiten) nachinstallieren. Und dazu kommt noch, dass wir die LaTeX-Build Fähigkeit auf Travis hinaufsetzen, da TeX/LaTeX nicht offiziell unterstützt wird.

Fehlerbehebung

Am einfachsten sucht man im tlmgr Repository nach der fehlenden Datei/Packet und fügt danach das fehlende Packet zur tlmgr install Linie im Skript.

tlmgr search --global -all <filename here>*

...
install:
  - 
  [...]
  - tlmgr install [...] new_package
...

OAuth Token in Environment Variable in Travis

Generiere über die Anleitung von Github ein OAuth Token für dein Konto mit den Berechtigungen repo oder nur public_repo. Danach kopierst du den erhaltenen Hash in eine Environment Variable namens GIT_AUTH in den Einstellungen von Travis für dein jeweiliges Repo.

PDF/A Compliance

Das Reglement der HSLU für Wirtschafts- und Bachelorarbeiten verlangt für die Abgabe von WebAbstract und Dokumentation die Einhaltung des PDF/A-Dateiformats. Wir erreich dies über das Packet pdfx und legen über \usepackage[a-2b,latxmp]{pdfx} sowohl den Standard (2A Basic) und eine externe Metadatendatei fest. Damit wird unser Dokument direkt in ein PDF/A2b-PDF kompiliert.

.xmpdata

Erstens ist es wichtig, dass die .xmpdata-Datei genau gleich heisst wie die .tex-Datei, da sie ansonsten von pdfx nicht erkannt wird. Zweitens verwenden wir nur ein Subset der verfügbaren Befehle für pdfx, genauere Details sind in der Dokumentation auf CTAN zu finden. Wichtig ist, dass Werte in gewissen Feldern (zum Beispiel die Autoren oder Keywords) mit einem speziellen Separator \sep getrennt werden können. Ein Beispiel:

...
\Author{AUTOR01\sep AUTOR02}
\Title{TITEL}
...

Was hat es mit "the glyph width information" in veraPDF auf sich

Kurzgesagt (unsere Hypothese): Die Schriftart die wir benutzen hat Sonderzeichen welche eine Breite von 0 angeben, was nicht akzeptiert ist. Es gibt nun zwei Arten mit diesem Fehler umzugehen:

1. Ignorieren, da das generierte PDF dennoch als PDF/A im gängigen Acrobat Reader erkannt wird
2. Eine andere Schriftart verwenden (zum Beispiel die standardmässige von KomaScript verwendete)

Schlusswort

Wir hoffen unsere Vorlage nimmt euch ein Bisschen Arbeit ab, damit ihr euch auf die Arbeit konzentrieren könnt. Viel Erfolg! Pascal & Dane