Dokumentation: Erweiterungen + Aufräumarbeiten (#100)

* reference extension recommendations, resolves #92

* reference latex workshop settings, resolves #21

* * various grammar or typo fixes
* make it clear that TeXstudio is an alternative and not needed for vscode
* make the first setup list unordered and change wording a little, to indicate that a fresh clone does not need an update right away (thinking about it, bad timing may occur here, lol)
* change wording of "Root-Ordner"; some folks might be tempted to mess with "/" or "/root"
* add link to python.org to mitigate ppl falling for fake websites
* add image of Python installer with emphasis on PATH

* Apply suggestions from code review

Co-authored-by: Oliver Kogel <[email protected]>
Co-authored-by: Felix Prillwitz <[email protected]>

* apply suggestions from review

* clarify 'variable' calling

Co-authored-by: Oliver Kogel <[email protected]>
Co-authored-by: Felix Prillwitz <[email protected]>

README.md

@@ -3,10 +3,14 @@
 Inoffizielles LaTeX-Template für Projektarbeiten für Technik-Studiengänge an der Dualen Hochschule Gera Eisenach
 
 # Inhaltsverzeichnis <!-- omit in toc -->
+
 - [Installation](#installation)
   - [LaTeX Installation](#latex-installation)
     - [Perl](#perl)
   - [Setup](#setup)
+    - [Visual Studio Code: empfohlene Erweiterungen](#visual-studio-code-empfohlene-erweiterungen)
+    - [Einstellen von TeXstudio zur Nutzung von `latexmk`](#einstellen-von-texstudio-zur-nutzung-von-latexmk)
+    - [Einstellen von LaTeX Workshop (VSCode)](#einstellen-von-latex-workshop-vscode)
 - [Latex Tipps](#latex-tipps)
   - ["Variablen"](#variablen)
   - [Environment (Umgebung)](#environment-umgebung)
@@ -24,7 +28,7 @@ Inoffizielles LaTeX-Template für Projektarbeiten für Technik-Studiengänge an
 - [Abkürzungen](#abkürzungen)
 - [Anlagenverzeichnis](#anlagenverzeichnis)
   - [Verwendung](#verwendung)
-- [Code einfügen mit Minted](#code-einfügen-mit-minted)
+- [Code mit Minted einfügen](#code-mit-minted-einfügen)
 - [Spezielle Abschnitte](#spezielle-abschnitte)
   - [SubSubSubSection](#subsubsubsection)
 - [Unicode Alphabete](#unicode-alphabete)
@@ -33,7 +37,7 @@ Inoffizielles LaTeX-Template für Projektarbeiten für Technik-Studiengänge an
 
 ## LaTeX Installation
 Eine Installation von MikTeX über [proTeXt](https://www.tug.org/protext/) wird empfohlen.
-Als Editor bieten sich beispielsweise [Visual Studio Code](https://code.visualstudio.com/) in Kombination mit der [latex-workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) Extension und [TeXstudio](https://www.texstudio.org/) an.
+Als Editor bieten sich beispielsweise [Visual Studio Code](https://code.visualstudio.com/) in Kombination mit der [latex-workshop](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) Extension oder alternativ [TeXstudio](https://www.texstudio.org/) an.
 
 >Bei einer bereits bestehenden Installation sollten die installierten Packages auf Updates überprüft werden. Andererseits kann es zu Problemen beim Bauen kommen.
 
@@ -47,44 +51,63 @@ Nutzer von macOS und Linux haben meistens schon ein vorinstalliertes Perl.
 Wenn man herausfinden möchte, ob man bereits ein funktionierendes Perl hat oder die unten genannte Installation erfolgreich verlief, kann man in einer Kommandozeile (Terminal) seiner Wahl ``perl -v`` ausführen.
 Ist Perl korrekt installiert, wird die Version ausgegeben:
 
-![Perl ist unter Windows korrekt installiert](assets/img/perl-windows.jpg)
+![Perl ist unter Windows korrekt installiert](assets/readme/perl-windows.jpg)
 
 Ist die Perl-Installation nicht vorhanden oder dem Terminal unbekannt, wird stattdessen folgendes ausgegeben:
 
-![Kein Perl installiert](assets/img/no-perl-windows.jpg)
+![Kein Perl installiert](assets/readme/no-perl-windows.jpg)
 
 **Installation unter Windows**
 
 Für Windows Nutzer empfiehlt sich Strawberry Perl, was [hier](https://strawberryperl.com/) erhältlich ist.
 
 ## Setup
 
-1. Das Repository downloaden, clonen, oder die Template Funktion nutzen, um ein eigenes Repository zu erstellen.
-2. Mit der Update-Datei (OS abhängig .bat/.sh) kann das Template aktualisiert werden
+* Das Repository downloaden, clonen, oder die Template Funktion nutzen, um ein eigenes Repository zu erstellen.
+* Mit der Update-Datei (OS abhängig .bat/.sh) kann ein bestehendes Template aktualisiert werden
 
 * ### **ACHTUNG** die Update-Datei (entsprechend OS)
   * **überschreibt** die Dateien im build Ordner
-    * eigene Anpassungen sollten über die Dateien im Root-Ordner geschehen
+    * eigene Anpassungen sollten über die Dateien im Wurzelverzeichnis des Projektes geschehen
   * **löscht** die mit git in Zusammenhang stehenden Ordner und Dateien (.git, .gitignore, .gitkeep)
 
 Das Projekt sollte sich nun bauen lassen.
 
-Wir empfehlen den `latexmk` Befehl zum kompilieren des Projekts.
-Während die Visual Studio Code Erweiterung "LaTeX Workshop" standardmäßig `latexmk` verwendet, ist bei TeXstudio eine Anpassung der Einstellungen erforderlich:
+Wir empfehlen den `latexmk` Befehl zum Kompilieren des Projekts.
+Während die Visual Studio Code Erweiterung "LaTeX Workshop" standardmäßig `latexmk` verwendet, ist bei TeXstudio eine Anpassung der Einstellungen erforderlich, siehe [hier](#einstellen-von-texstudio-zur-nutzung-von-latexmk)
+
+### Visual Studio Code: empfohlene Erweiterungen
+
+Wir empfehlen für die Arbeit in Visual Studio Code ausgewählte Erweiterungen, die sowohl für das Schreiben mit LaTeX, als auch für das Studium an der DHGE<!--ähem Plantuml--> hilfreich sind.
+Um sie zu prüfen und ggf. zu installieren, kann in dem Erweiterungsmenü nach `@recommended` gesucht werden:
 
-**Einstellen von TeXstudio zur Nutzung von `latexmk`:**
+![Empfohlene Erweiterungen in VS Code](assets/readme/vscode-recom-exts.png)
+
+### Einstellen von TeXstudio zur Nutzung von `latexmk`
 
 1. Die TeXstudio-Einstellungen öffnen: Im Menüband `Optionen`, dann `TeXstudio konfigurieren...` anklicken
 2. Im Abschnitt `Befehle` sichergehen, dass der Latexmk-Eintrag befüllt ist, z.B. mit: `latexmk.exe -pdf -silent -synctex=1 %`
 3. Im Abschnitt `Erzeugen` den Standardcompiler `Latexmk` in der Drop-down Liste auswählen
 
+### Einstellen von LaTeX Workshop (VSCode)
+
+Die Erweiterung "LaTeX Workshop" für Visual Studio Code bietet eine Vielzahl von Einstellungsmöglichkeiten und kann auf die individuellen Bedürfnisse angepasst werden.
+z.B. kann ein externer PDF-Betrachter oder ein automatisches Build-Intervall eingerichtet werden.
+Die Einstellungen für die Erweiterung findet man am Ende der Einstellungen von Visual Studio Code selbst:
+
+1. im Menüband `Datei` anklicken
+2. über `Einstellungen` hovern und dort `Einstellungen` anklicken.
+3. Am Ende der Liste `Erweiterungen` aufklappen und das Kapitel `LaTeX` anklicken.
+
+![Einstellungen für LaTeX Workshop](assets/readme/vscode-latex-settings.jpg)
+
 # Latex Tipps
 
 <!-- todo: add more -->
 Ein relativ simples [LaTeX-Tutorial](https://www.latex-tutorial.com/tutorials/first-document/) zum einfachen Einstieg in die Welt von TeX.
 > _ist allerdings durch das Template nicht nötig, nachfolgendes sollte ausreichen_
 
-Für einen Einstieg in das wissenschaftliche Schreiben an sich bietet sich ein Artikel von Sebastian Hahnert an, der ebenfalls auf LaTeX eingeht: [Wissenschaftliches Schreiben Schnelleinstieg](https://github.com/sebinside/WissenschaftlichesSchreiben-Schnelleinstieg)
+Für einen Einstieg in das wissenschaftliche Schreiben an sich bietet sich ein Artikel von Sebastian Hahner an, der ebenfalls auf LaTeX eingeht: [Wissenschaftliches Schreiben Schnelleinstieg](https://github.com/sebinside/WissenschaftlichesSchreiben-Schnelleinstieg)
 
 ## "Variablen"
 
@@ -94,20 +117,20 @@ Variablen gibt es in TeX an sich nicht wie in anderen Sprachen.
 \def\<variablenName>{<variablenWert>}
 ```
 
-Der `\def` Befehl definiert ein Command der letztendlich dem folgendem entspricht
+Der `\def` Befehl definiert ein Command der letztendlich Folgendem entspricht:
 
 ```latex
 \newcommand{\<variablenName>}{<variablenWert>}
 ```
 
 Richtig werden diese "Variablen" dann durch `\<variablenName>`**`{}`** aufgerufen.
 
-Es ist aber auch möglich sie einfach nur durch `\<variablenName>` aufzurufen.\
-> Hier ist zu beachten ist das nach der Variable das Leerzeichen fehlt wird, da dieses als Argument aufgenommen wird
+Alternativ ist aber auch möglich, sie durch `\<variablenName>` aufzurufen.\
+> Hier ist zu beachten, dass nach der Variable das Leerzeichen fehlen wird, da dieses als Argument des Befehls aufgenommen wird
 
 ## Environment (Umgebung)
 
-Ein Codeblock welcher bestimmte Anläufe vor und nach dem eigenen Code laufen lässt.
+Ein Codeblock, welcher bestimmte Abläufe vor und nach dem eigenen Code laufen lässt.
 
 ```latex
 \begin{<environment>}
@@ -125,7 +148,7 @@ Ein Codeblock welcher bestimmte Anläufe vor und nach dem eigenen Code laufen l
 
 ## Zitat als Fußnote einfügen
 
-Dafür wird der `footcite` Befehl genutzt. Dieser bietet folgende Syntax:
+Dafür wird der `footcite` Befehl genutzt. Dieser besitzt folgende Syntax:
 
 ```latex
 \footcite[Postnote]{literatur_id}
@@ -220,7 +243,7 @@ Beispiel:
 \end{figure}
 ```
 
-- `[H]` - entspricht dem fixieren an der Stelle im Text
+- `[H]` - entspricht dem Fixieren an der Stelle im Text
 - `[scale=0.75]` - skaliert das Bild auf 75% der Originalgröße
 - `fig:anlagentest` - `fig:` oder `tab:` ist ein typischer Anfang von Referenzen für entsprechend `figure` oder `table` Umgebung
 
@@ -233,7 +256,7 @@ Beispiel:
 kann mit bis zu sechs Argumenten aufgerufen werden:
 
 1. **Optional** Float Position, standardmäßig `h`
-1. Relativer bild-path mit oder ohne Dateiendung (relativ zum `./assets/img` Ordner, kann in `template.tex` angepasst werden)
+1. Relativer Bild-Pfad mit oder ohne Dateiendung (relativ zum `./assets/img` Ordner, kann in `template.tex` angepasst werden)
 1. `\includegraphics` Optionen (leer lassen für Standard)
 1. Bildunterschrift
 1. Label für die Figure/Grafik
@@ -248,12 +271,12 @@ Beispiel:
 
 ***
 
-Wir empfehlen den Befehl als Snippet im Text-Editor zu hinterlegen.
+Wir empfehlen, den Befehl als Snippet im Text-Editor zu hinterlegen.
 In Visual Studio Code kann ein Snippet folgendermaßen konfiguriert werden:
 
 1. _CTRL+Shift+P_
 2. `Preferences: Configure User Snippets`
-3. bereits existierenden latex Snippet File auswählen **oder** `New Global Snippets File...`
+3. bereits existierenden LaTeX Snippet File auswählen **oder** `New Global Snippets File...`
 4. Snippet einfügen:
 
 ```json
@@ -281,8 +304,8 @@ Beispielweise:
 
 ```latex
 \DeclareAcronym{dhge}{
-	short = {DHGE},
-	long = {Duale Hochschule Gera-Eisenach}
+  short = {DHGE},
+  long = {Duale Hochschule Gera-Eisenach}
 }
 ```
 
@@ -293,7 +316,7 @@ Im Fließtext wird dann mit
 ```
 
 die Abkürzung aufgerufen.
-Dies sind die Angaben, die mindestens benötigt werden. Es gibt weitere Einstellungsmöglichkeiten bei dem Deklarieren von Abkürzungen, die in der unten stehenden Dokumentation nachgelesen werden können. Eine sinnvolle Auswahl davon:
+Dies sind die Pflicht-Argumente. Es gibt weitere Einstellungsmöglichkeiten bei dem Deklarieren von Abkürzungen, die in der unten stehenden Dokumentation nachgelesen werden können. Eine sinnvolle Auswahl davon:
 
 ```latex
 \DeclareAcronym{1}{
@@ -304,7 +327,9 @@ Dies sind die Angaben, die mindestens benötigt werden. Es gibt weitere Einstell
   alt = {8}
   }
 ```
+
 ODER
+
 ```latex
 \DeclareAcronym{1}{
   short = {2},
@@ -314,6 +339,7 @@ ODER
   alt = {8}
   }
 ```
+
 1. ID der Abkürzung, damit wird im Fließtext später referenziert.
 2. Die Abkürzung selbst
 3. Der ausgeschriebene Begriff
@@ -326,15 +352,19 @@ ODER
 Die Angaben 4 bis 8 sind optional.
 
 Die Pluralform lässt sich mit
+
 ```latex
 \acp{1}
 ```
+
 aufrufen, die Alternativform mit
+
 ```latex
 \aca{1}
 ```
 
 Beispiel:
+
 ```latex
 \DeclareAcronym{jpg}{
   short = {JPEG},
@@ -344,7 +374,9 @@ Beispiel:
   alt = {JPG}
   }
 ```
+
 ODER
+
 ```latex
 \DeclareAcronym{jpg}{
   short = {JPEG},
@@ -354,7 +386,9 @@ ODER
   alt = {JPG}
   }
 ```
+
 Aufruf:
+
 ```latex
 \ac{jpg} % Normale Form
 \acp{jpg} % Plural-Form
@@ -365,7 +399,7 @@ Das Abkürzungsverzeichnis wird dann automatisch erstellt. Dabei ist zu beachten
 
 ***
 
-Für mehr Informationen kann die [Acro Package Documentation](https://mirror.physik.tu-berlin.de/pub/CTAN/macros/latex/contrib/acro/acro-manual.pdf) gelesen werden
+Für mehr Informationen kann die [Acro Package Documentation](https://mirror.physik.tu-berlin.de/pub/CTAN/macros/latex/contrib/acro/acro-manual.pdf) gelesen werden.
 
 # Anlagenverzeichnis
 
@@ -377,7 +411,7 @@ Für mehr Informationen kann die [Acro Package Documentation](https://mirror.phy
   * hierbei ist zu beachten:
     * die Anlage muss sich in einer Umgebung vom Typ `figure` oder `table` befinden
     * die Anlage benötigt eine Beschriftung `\caption{}`
-  * ein Label ist nicht nötig für eine automatische Verknüpfung im Anlagenverzeichnis
+  * ein Label ist für eine automatische Verknüpfung im Anlagenverzeichnis nicht nötig
   * der vorgefertigte Befehl `\dhgefigure`, kann verwendet werden, da dieser beide Anforderungen erfüllt
   * siehe Beispiel `build/tests/anlagen.tex`
 
@@ -392,16 +426,18 @@ Beispiel:
 \end{table}
 ```
 
-# Code einfügen mit Minted
+# Code mit Minted einfügen
 
 **Hier eine kurze Anleitung für das Minted Package. Damit lässt sich Code mit Syntaxhervorhebung direkt in LaTeX einfügen.**
 
-1. Python installieren
-1. Sicherstellen, dass die Python Umbebungsvariable gesetzt ist
-1. Pygments installieren (`pip install Pygments`)
-1. `\usepackage {minted}` in `build/package.config.tex` hinzufügen
-1. `--shell-escape` flag im Compiler-Aufruf setzen
-1. [Minted Kurz-Anleitung](https://www.overleaf.com/learn/latex/Code_Highlighting_with_minted) oder [Minted Documentation](https://ctan.mc1.root.project-creative.net/macros/latex/contrib/minted/minted.pdf) lesen
+1. Python [hier](https://www.python.org/) herunterladen und installieren und **sicherstellen, dass Python zur Umgebung (PATH) hinzugefügt ist**
+
+![Python PATH](assets/readme/python-path.png)
+
+2. Pygments installieren (`pip install Pygments`)
+3. `\usepackage {minted}` in `build/package.config.tex` hinzufügen
+4. `--shell-escape` flag im Compiler-Aufruf setzen
+5. [Minted Kurz-Anleitung](https://www.overleaf.com/learn/latex/Code_Highlighting_with_minted) oder [Minted Documentation](https://ctan.mc1.root.project-creative.net/macros/latex/contrib/minted/minted.pdf) lesen
 
 ***
 
@@ -428,6 +464,6 @@ Beispiel:
 
 # Unicode Alphabete
 
-Falls chinesische, japanische o.ä. Alphabete verwendet werden müssen (bsp. bedingt durch Autoren), ist die einfachste Methode das `CJKutf8` Package zu laden.
+Falls chinesische, japanische o.ä. Alphabete verwendet werden müssen (bspw. bedingt durch Autoren), ist die einfachste Methode, das `CJKutf8` Package zu laden.
 
 Eine Anleitung finden Sie in [diesem Artikel](https://www.overleaf.com/learn/latex/chinese).