htlle-da-vorlage/README.md

HTLLE-DA-Vorlage
================

Diese Vorlage ist zur Erstellung der Diplomarbeiten an der HTL Leoben gedacht. 
*Bitte sprechen Sie mit Ihren Betreuern ab, ob Sie die Arbeit mit Hilfe dieses Templates verfassen dürfen.*


Das hier vorliegende Template sollte die Erstellung von Diplomarbeiten in Teams soweit wie möglich vereinfachen.

Deshalb setzen wir auf die Verwendung von freien Technologien welche ohne Lizenzkosten auf jedem Rechner installiert werden dürfen:

* [GIT](https://git-scm.com/) zur Verwaltung und Versionierung der Diplomarbeit. 
* [Make](https://www.gnu.org/software/make/) zum Aufruf und zur orchestrierung der Werkzeuge
* [Pandoc](https://pandoc.org/) zur Transformation von [Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) Dateien zu LaTex Dateien, sowie 
* [BibTex](http://www.bibtex.org/) zur Erstellung von Literaturverzeichnissen und Referenzen innerhalb des Dokuments  
* [TexLive](https://www.tug.org/texlive/) zur erstellung des fertigen PDFs aus dem generierten LaTex Dokument


Zur Erstellung der Arbeit sollte immer das neuest Template aus dem Repository https://itsp.htl-leoben.at/git/Hg/HTLLE-DA-Vorlage verwendet werden. Das dort abgelegte Template wird von hg gepflegt und enthält die jeweils letztgültige (und mit der Direktion abestimmte) Fassung.


Vorbereitung des eigenen Rechners
=================================

Damit die DA gebaut werden kann müssen mehrere Programme installiert sein. Theoretisch funktioniert das auch mit 'purem' Windows, aber einfacher ist es die Arbeit mit Hilfe von Linux zu erstellen. Aus diesem Grund finden Sie hier nur die Anweisungen die sich auf einem **Ubuntu 18.04 LTE**  beziehen.

## Windows

Wenn man Windows 10 als primäres Betriebssystem verwendet habt man zwei Möglichkeiten um zu einer Linux Umgebung zu kommen:

1. Installation einer virtuellen Maschine auf der ein Linux läuft (z.B: mit [HyperV](https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v), [VmWare](https://www.vmware.com/at/products/workstation-player.html), [VirtualBox](https://www.virtualbox.org/) oder einem anderen Virtualisierer) -> Dann erhält man eine VM welche man zum bearbeiten der VM extra starten muss
2. Aktivierung des [Windows Subsystem für Linux](https://docs.microsoft.com/en-us/windows/wsl/about) anhand [dieser Anleitung](https://docs.microsoft.com/en-us/windows/wsl/install-win10) welches genau so eine Umgebung erzeugt und bei der diw Windows und Linux Welt miteinenader zusammenwachsen.

Es ist egal für welche der beiden Varianten man sich entscheidet - funktionieren werden technisch gesehen beide gleich gut ... wobei die WSL Variante sicherlich mehr Comfort bietet. 

## Linux


Zuerst müssen (einmalig) die notwendigen Pakete in der Linux Umgebung installiert werden. Dieser Vorgang kann einige Zeit in Anspruch nehmen weil ca. 3-4 GB an Daten installiert werden.

```
$ sudo apt-get install git build-essential pandoc texlive-full
```

Grundlegende Schritte
=====================

## Erstellen einer Diplomarbeit

Wenn Sie mit einer neuen Diplomarbeit beginnen, dann gehen Sie am besten wie folgt vor:

### Erstellen eines leeren GIT Repositories in dem Sie Ihre DA Daten verwelten werden.

Es ist prinzipiell egal auf welchem GIT Server sie Ihr Repository hosten. Wir empfehlen dies aber auf dem HTL eigenen `https://itsp.htl-leoben.at/git` Server zu machen.

```
~/Diplomarbeit$ git init
git commit -m "first commit"
git remote add origin https://itsp.htl-leoben.at/git/schueler/Diplomarbeit_JAHR.git
git push -u origin master
```

### Hinzufügen des Teplates als git-submodul
Danach wird dieses Repository als [git-submodule](https://git-scm.com/docs/git-submodule) dazugeklont:

```
git submodule add https://itsp.htl-leoben.at/git/Hg/HTLLE-DA-Vorlage.git
```

Falls das Template durch hg geändert wird erhalten Sie mit Hilfe des Befehls `git submodule update` erhalten Sie die jeweils aktuellste Version des Templates.

### Erstellen der Inhaltsfiles für die DA

Die Inhaltsdateien legen Sie in Ihrem Repository ab. Am besten Sie beginnen damit, die Inhlatsdateien aus dem Template als Grundlage für Ihre DA zu verwenden. Sie können diese aus dem Template ganz einfach herkopieren und anschließend bearbeiten.

```
$ cp ./HTLLE-DA-Vorlage/source/*.md .
```

Damit sollten sie am Ende dann in etwa so eine Verzeichnisstruktur haben

```
$ tree
.
├── 10-einleitung.md               <= Kapitel: Einleitung
├── 20-zielsetzung.md              <= Kapitel: Zielsetzung
├── 30-ausarbeitungen.md           <= Kapitel: Ausarbeitungen
├── 31-ausarbeitung_schueler1.md   <=          Ausarbeitung Schueler A
├── 32-ausarbeitung_schueler2.md   <=          Ausarbeitung Schueler B
├── 40-zusammenfassung.md          <= Kapitel: Zusammenfassung
│
├── literatur.bib                  <= Das ist das Literaturverzeichnis
├── metadata.yaml                  <= Grundlegende Informationen zur Diplomarbeit
│
├── img                            <= Hier kommen alle Ihre Bilder rein
│   ├── graph.png
│   └── screenshot_eclipse.png
│
├── pdfs                           <= PDFs für den Anhang (referenziert in metadata.yaml)
│   ├── begleitprotokolle.pdf
│   ├── HTL-DA-Vereinbarung.pdf
│   └── projekthandbuch.pdf
│
│  
└── HTLLE-DA-Vorlage
    ├──                            ... Inhalte aus der DA Vorlage
    └──                            ... wurden hier ausgeblendet


```

Es ist wichtig dass diese Verzeichnisstruktur so beibehalten wird, weil sonst der Build-prozess schief gehen kann. Achten Sie auf Groß und Kleinschreibung der Dateien und verzeichnisse. 

Normalerweise sollten sie mit diesen Dateien auskommen. Sie können den Inhalt dieser Dateien (unter Einhaltung der entsprechenden Formatierungsvorschriften) durch Ihren Inhalt ersetzen.
Es ist normalerseise nicht notwendig weitere Dateien einzufügen, denn Dinge wie das Deckblatt, Eidesstattliche Erklärung, div. Verzeichnisse werden automatisch erstellt und gleich korrekt fomatiert.
Hier nochmals eine Erklärung der verschiedenen Dateien:

* Die `*.md` Dateien im Basisverzeichnis bilden den eigentlichen Inhalt Ihrer Diplomarbeit. Sie können diese Dateien mit jedem handelsüblichen Editor (zur Not auch direkt in Gitea) bearbeiten. Die Nummerierung am Anfang dient dazu, dass die Reihenfolge in der Diplomarbeit passt. So erscheint z.B: der Inhalt der Datei __20-zielsetzung.md__ nach __10-einleitung.md__ und vor __30*.md__. Die im Template angebotene Reihenfolge ist jene wie sie in der Diplomarbeit gewünscht ist.  
* Das `/img` Verzeichnis beinhaltet alle Grafigen zur Diplomarbeit. Die können hier zur besseren Strukturierung auch gerne Unterverzeichnisse erstellen. Folgendes ist bei der Verwendung von Grafiken zu beachten:
    * Achten Sie darauf dass sie dort nur `*.jpg` und `*.png` Dateien ablegen 
    * Groß und Kleinschreibung müssen beachtet werden. So werden unter Linux die Datein `Hallo.jpg` und `hallo.jpg` als zwei unterschiedliche Dateien angesehen. Unter Windows hingegen nicht.
    * Machen Sie Grafiken in guter Auflösung (> 72 dpi) und Achten Sie darauf dass diese nicht zu viel oder zu wenig Inhalt zeigen weil die Grafiken auf max. Seitenbreite skaliert werden können und dann entweder zu klein oder zu pixelig erscheinen.
    * Orientieren sie die Grafiken so wie sie selbige in der Arbeit haben wollen. Wenn sie Grafiken um 90 Grad drehen, dann drehen Sie alle Grafiken in die selbe Reichtung !
* Das `/pdfs` Verzeichnis beinhaltet Dateien welche im Appendix (auszugsweise oder ganz) eingefügt werden. Damit dies geschieht müssen sie aber im `metadata.yaml` korrekt referenziert werden. Es ist keine Schande hier viele Dateien abzulegen - sofern diese einen Bezug zur Diplomarbeit haben.


## Bauen der Diplomarbeit

Damit das PDF für die Diplomarbeit erstellt wird muss (aus Ihrem Basisverzeichnis heraus) folgender Befehl abgesetzt werden:

```
make pdf -C HTLLE-DA-Vorlage INPUTDIR=$(pwd)
```

Danach erscheint (sofern alles gut geht) die Datei `HTLLE-DA-Vorlage/output/diplomarbeit.pdf`. Sollte die Datei bereits von einem früheren Lauf her existiert haben wird sie einfach überschrieben.
Sollte die Arbeit nicht erfolgreich geabut werden können, dann kann in der Datei `pandoc.log` der Grund dafür heruasgefunden werden.