Merge branch '2020-create-own-script' of git.stuve-bamberg.de:latex/latex-skript into 2020-create-own-script

Makefile

@@ -81,7 +81,7 @@ publication-pdf-with-solutions: clean publication-dir main.tex
 # Build a ZIP file with tasks and without solutions
 publication-zip-with-exercises: clean publication-dir main.tex
 	rm -rf temp/*
-	cp --parents main.tex praeamble.tex commands.tex content/* graphics/* listings/**/*{.tex,pdf,bib} temp/
+	cp --parents main.tex praeamble.tex commands.tex content/* graphics/* listings/**/*{.tex,pdf,bib,java} temp/
 	cp --parents exercises/**/* temp/
 	rm -f temp/exercises/**/*.done.{tex,bib}
 	rm -f temp/exercises/**/*.rend.tex
@@ -92,7 +92,7 @@ publication-zip-with-exercises: clean publication-dir main.tex
 # Build a ZIP file with tasks and solutions
 publication-zip-with-solutions: clean publication-dir main.tex
 	rm -rf temp/*
-	cp --parents main.tex praeamble.tex commands.tex content/* graphics/* listings/**/*.{tex,pdf,bib} temp/
+	cp --parents main.tex praeamble.tex commands.tex content/* graphics/* listings/**/*.{tex,pdf,bib,java} temp/
 	cp --parents exercises/**/* temp/
 	rm -f temp/exercises/**/*.raw.{tex,bib}
 	find temp/ -name '*.done.*' -exec bash -c 'sed "s/\.done\./\./g" <<<{} | xargs mv {}' \;

README.md

@@ -1,6 +1,6 @@
 # LaTeX Script by Fachschaft WIAI
 
-This script introduces the most fundamental LaTeX mechanisms to get students started. It is used both as a reference and as exercise material for our [LaTeX workshop](https://wiai.de/latex-weekend), a **two-day tutorial aimed at students from various backgrounds**. At the moment, it is only available in German. The following topics are covered:
+This script introduces the most fundamental LaTeX mechanisms to get learners started. It is used both as a reference and as exercise material for our [LaTeX workshop](https://wiai.de/latex-weekend), a **two-day tutorial aimed at students from various backgrounds**. At the moment, it is only available in German. The following topics are covered:
 
 * general introduction to the LaTeX system 
 * basic document structure
@@ -21,23 +21,76 @@ Most chapters contain exercises to be performed within the script itself, practi
 
 ## Requirements
 
-Compiling the script requires a working LaTeX installation.
-For sourcecode listings, we are using Pygments and Python3.
+Compiling the script requires a working [LaTeX installation](https://tug.org/texlive/).
+For sourcecode listings, we are using [Pygments](https://pygments.org/) and [Python3](https://www.python.org/).
 The Makefile comes in handy for compiling the different versions of the script (see usage section).
+For learners, we recommend using [TeXstudio](https://www.texstudio.org/) to compile the script.
 
-TODO: Add detailed explanation.
+## Project Structure
+
+```
+latex-skript/
+├── commands.tex
+├── compile_listings
+├── compile_tasks
+├── content
+│   ├── basic-document-structure.tex
+│   ├── basic-functionality.tex
+│   └── …
+├── exercises
+│   ├── basic-document-structure
+│   ├── footnotes
+│   └── …
+├── graphics
+│   ├── benzene-ring.pdf
+│   ├── cc-by-sa.png
+│   └── …
+├── listings
+│   ├── basic-document-structure
+│   ├── formatting-paragraphs
+│   └── …
+├── main.tex
+├── Makefile
+├── praeamble.tex
+├── public
+└── README.md
+```
+
+* **`main.tex`** is the entrypoint. It includes the preamble (`preamble.tex`), our custom commands (`commands.tex`) as well as all sections.
+* **`content`** comprises the individual chapters of this script.
+* Most chapters include a task that can be found in the **`exercises`** folder.
+* **`public`** is the folder where all packed-up versions of the script are moved to, once they have been created using the `Makefile` and the command `make publication`. There are two zip archives of this repository (one containing only the exercises and one with solutions included) as well as three PDF versions (one with the content only, one with exercises, and one with exercises and solutions).
+* `compile_listings` and `compile_commands` are two **utility bash scripts**. They produce a rendered and cropped PDF version of all `.tex` files within the `listings`/`exercises` folders and their subfolders. Rendered listings remain in `listings` whereas tasks are moved to the **`graphics`** folder afterwards. The compiled tasks are necessary for students who receive the project archive, but should not be given the sourcecode of tasks, e.g., if an exercise demands them to code up a table based on a pre-coded example.
 
 ## Usage
 
-TODO: Describe the project setup.
+**For beginners**: A PDF version of the script can be found in the “releases” section. It will give you an overview of how to use any LaTeX project. For this, have a look at the “Erste Schritte mit LaTeX” section.
+
+**Commandline usage**: The project can be compiled by running a LaTeX compiler on `main.tex`. Note that we make (heavy) use of the Pygments package, which requires additional installation (see section above) and a flag (`--shell-escape`) that has to be passed to the compiler. To configure TeXstudio with Pygments, see the chapter “Quelltext-Listings” (especially “10.2 – Compilerbefehl ändern”) in the script. A simple command would be:
+
+```sh
+$ pdflatex --shell-escape main.tex
+```
+
+Run the command twice to generate the table of contents and other registers. Once the literature tasks are being worked on, compilation requires an additional call to BibTeX:
+
+```sh
+$ pdflatex --shell-escape main.tex
+$ bibtex main.aux
+$ pdflatex --shell-escape main.tex
+$ pdflatex --shell-escape main.tex
+```
 
 ## Contributing
 
 You are welcome to contribute to this project by creating issues, opening pull requests, or reporting bugs. Note that our goal is to keep the content rather condensed, so we might not choose to incorporate further sections.
 
-These are the contributors so far:
-TODO: Add them.
+These are the main contributors so far:
+* Evelyn Fradtschuk
+* Florian Knoch
+* Christian Kremitzl
+* Bernhard Luedtke
 
 ## License
 
-TODO: Add license.
+The LaTeX Script was created by Fachschaft WIAI, the Student Council of the faculty of Information Systems and Applied Computer Sciences at University of Bamberg. It is licensed under the creative commons licence “Attribution-ShareAlike 4.0 International” (CC BY-SA 4.0): http://creativecommons.org/licenses/by-sa/4.0/. Usage permissions beyond the scope of this license might be granted upon request.

content/first-steps-with-latex.tex

@@ -0,0 +1,11 @@
+\chapter*{Erste Schritte mit \LaTeX}
+Bevor wir ins Arbeiten mit \LaTeX{} einsteigen können, müssen wir es natürlich erst mal installieren. Achtet bitte darauf, dass ihr \emph{zuerst} den Compiler und danach einen Editor installiert.
+
+\section*{Compiler}
+Zunächst zum Compiler. Ihn brauchen wir, um den Quelltext, den wir schreiben, in ein PDF umzuwandeln. Hier gibt es für verschiedene Betriebssysteme unterschiedliche Compiler, wie etwa MikTeX für Windows\footnote{\url{https://miktex.org/download}}, MacTex für MacOS\footnote{\url{http://tug.org/mactex/}} und TeXLive für Linux-Distributionen\footnote{Sofern ihr eine debianbasierte Linux-Distribution verwendet, kann der Compiler mittles \mintinline{bash}{sudo apt install texlive-full} installiert werden. Für andere Distributionen findet ihr eine Anleitung unter \url{https://tug.org/texlive/doc/texlive-en/texlive-en.html\#installation}.}. Bestenfalls installiert ihr die volle Version mit allen Paketen.
+
+\section*{Editor}
+Sobald ihr das gemacht habt, könnt ihr euch auch schon einen Editor herunterladen, in dem ihr eure \LaTeX-Dokumente gerne schreiben möchtet. Dafür ist eigentlich jeder Editor geeignet (notepad++, Atom, VS Code, usw.). Wir empfehlen für Anfänger jedoch ein Programm, das \LaTeX-spezfische Funktionen besitzt, wie etwa TeXstudio\footnote{Eine aktuelle Version findet ihr unter \url{https://www.texstudio.org/}.}.
+
+\section*{Das erste Mal Kompilieren}
+Öffnet nun die Datei \mintinline{bash}{main.tex} und kompiliert sie durch Druck auf \faForward. Was ist in dem Ordner passiert, in dem die Datei liegt?

exercises/basic-document-structure/task.tex

@@ -1,5 +1,5 @@
 \begin{enumerate}
-	\item In eurem \LaTeX{}-Projekt im Ordner \mintinline{latex}{exercises/basic-document-structure} findet ihr eine Datei namens \mintinline{latex}{document-structure.raw.tex}. Öffnet die Datei in eurem präferierten Editor, packt das Dokument in eine \mintinline{latex}{document}-Umgebung und fügt eine Präambel ein, um euer erstes \LaTeX -Dokument zu erstellen.
+	\item Im Ordner \mintinline{latex}{exercises/basic-document-structure} findet ihr eine Datei namens \mintinline{latex}{document-structure.tex}. Öffnet die Datei, kopiert den Text und fügt ihn in eine neue Datei ein, die ihr beispielsweise \mintinline[breaklines, breakbytokenanywhere]{latex}{document- structure-solution.tex} nennt. Packt den Text in der neuen Datei in eine \mintinline{latex}{document}-Umgebung und fügt eine Präambel ein, um euer erstes \LaTeX -Dokument anschließend kompilieren zu können. Kompiliert nun das neue Dokument. 
 	\item Herzlichen Glückwunsch, ihr habt euer erstes eigenes \LaTeX -Dokument erstellt und kompiliert. Wie euch vielleicht aufgefallen ist, sind die Absätze im Dokument mit \mintinline{latex}{\\} erstellt worden. Ersetzt diese durch richtige Absätze.
 	\item Nun ist es an der Zeit, das Dokument etwas zu strukturieren. Verwendet für die Überschriften die passenden \LaTeX -Befehle (\mintinline{latex}{\section}, \mintinline{latex}{\subsection}, usw.) und fügt anschließend ein Inhaltsverzeichnis in euer Dokument ein.
 \end{enumerate}

exercises/footnotes/task.tex

@@ -1,3 +1,3 @@
-Integriert im nachstehenden Text das Statement \glqq{}Stand: März 2021\grqq{} in eine Fußnote. Fügt außerdem eine klickbare URL als Fußnote zum Download Java Development Kit (https://www.oracle.com/java/technologies/javase-downloads.html) ein.
+Integriert im Text der Datei \mintinline{bash}{exercises/footnotes/footnotes.tex} das Statement \glqq{}Stand: März 2021\grqq{} in eine Fußnote. Fügt außerdem eine klickbare URL als Fußnote zum Download Java Development Kit (https://www.oracle.com/java/technologies/javase-downloads.html) ein.
 
 \exercisematerial{exercises/footnotes/footnotes}

exercises/graphics/task.tex

@@ -1,3 +1,3 @@
-Bei den Übungsaufgaben findet ihr im Ordner \mintinline{latex}{graphics} eine Bilddatei namens \mintinline{latex}{latex-logo.png}. Fügt diese genau unterhalb dieser Aufgabenstellung ein. Das Bild soll zentriert eingebunden werden und über eine Bildunterschrift verfügen. Passt die Größe außerdem an die Breite der Seite (\mintinline{latex}{\textwidth}) an.
+Bei den Übungsaufgaben findet ihr im Ordner \mintinline{latex}{graphics} eine Bilddatei namens \mintinline{latex}{latex-logo.png}. Fügt das Bild in die Datei \mintinline{bash}{exercises/graphics/graphics.tex} ein. Sorgt dafür, dass das Bild genau unter diesem Text erscheint. Das Bild soll außerdem zentriert eingebunden werden und über eine Bildunterschrift verfügen. Passt die Größe außerdem an die Breite der Seite (\mintinline{latex}{\textwidth}) an.
 
 \exercisematerial{exercises/graphics/graphics}

exercises/lists/task.tex

@@ -1,3 +1,3 @@
-Formatiert das nachstehende Rezept als ungeordnete Liste (\mintinline{latex}{itemize}) mit den Elementen \emph{Zutaten} und \emph{Arbeitsschritte}. Innerhalb dieser soll eine kompakte, ungeordnete Liste (\mintinline{latex}{compactitem}) der Zutaten erstellt werden. Die Arbeitsschritte hingegen sollen als kompakte, geordnete Liste dargestellt werden.
+Formatiert das Rezept in der Datei \mintinline{bash}{exercises/lists/lists.tex} als ungeordnete Liste (\mintinline{latex}{itemize}) mit den Elementen \emph{Zutaten} und \emph{Arbeitsschritte}. Innerhalb dieser soll eine kompakte, ungeordnete Liste (\mintinline{latex}{compactitem}) der Zutaten erstellt werden. Die Arbeitsschritte hingegen sollen als kompakte, geordnete Liste dargestellt werden.
 
 \exercisematerial{exercises/lists/lists}

exercises/literature/task.tex

@@ -1,5 +1,5 @@
 \begin{enumerate}
-  \item Sucht bei Google Scholar eurer Wahl die Bib\TeX-Einträge für folgende \LaTeX-Handbücher:
+  \item Sucht bei Google Scholar die Bib\TeX-Einträge für folgende \LaTeX-Handbücher:
   \begin{itemize}
     \item Leslie Lamport (1994): \LaTeX. A Document Preparation System.
     \item Dilip Datta (2017): \LaTeX\ in 24 Hours. A Practical Guide for Scientific Writing.
@@ -10,7 +10,7 @@
   \item Fügt die Bib\TeX-Einträge in die Bib\TeX-Datei ein. Wählt hierfür aus Google Scholar und dblp die aus eurer Sicht geeigneteren Einträge.
   \item Vergebt aussagekräftige Bib\TeX-Keys.
   \item Bindet die Bib\TeX-Datei an einer geeigneten Stelle ein, an der später auch das Literaturverzeichnis zu sehen sein soll.
-  \item Zitiert die drei Handbücher im untenstehenden Text.
+  \item Zitiert die drei Handbücher in der Datei \mintinline{sh}{exercises/literature/literature.tex}.
   \item Wählt den Bibliographiestil \mintinline{sh}{natdin}.
   \item \textbf{Hinweis}: Sollte das Kompilieren fehlschlagen, kann es hilfreich sein, einmal alle Hilfsdateien (\mintinline{sh}{main.aux/bbl/blg/loc/out/pdf/soc/toc}) zu löschen und neu zu kompilieren.
 \end{enumerate}

exercises/references/task.tex

@@ -1,3 +1,3 @@
-Ersetzt im nachstehenden Text die Phrasen \enquote{in der Abbildung} und \enquote{Das nachstehende Quelltext-Listing} jeweils durch eine Referenz auf das Bild und auf das Quelltext-Listing. Nutzt dafür den Befehl \mintinline{latex}{\cref}. Achtet darauf, dass ihr zunächst Labels für die Elemente, die ihr referenzieren wollt, vergeben müsst. Hüllt das Quelltext-Listing dafür zunächst in eine Umgebung namens \mintinline{latex}{listing} und fügt noch eine Beschriftung hinzu. Achtet auch auf geeignete Präfixe vor den Labels.
+Ersetzt im Text in der Datei \mintinline{bash}{exercises/references/references.tex} die Phrasen \enquote{in der Abbildung} und \enquote{Das nachstehende Quelltext-Listing} jeweils durch eine Referenz auf das Bild und auf das Quelltext-Listing. Nutzt dafür den Befehl \mintinline{latex}{\cref}. Achtet darauf, dass ihr zunächst Labels für die Elemente, die ihr referenzieren wollt, vergeben müsst. Hüllt das Quelltext-Listing dafür zunächst in eine Umgebung namens \mintinline{latex}{listing} und fügt noch eine Beschriftung hinzu. Achtet auch auf geeignete Präfixe vor den Labels.
 
 \exercisematerial{exercises/references/references}

exercises/special-characters/task.tex

@@ -1,5 +1,5 @@
 \begin{enumerate}
-	\item Im folgenden Text findet ihr eine Reihe an Abkürzungen. Ersetzt die Leerzeichen innerhalb der Abkürzungen durch schmale Leerzeichen. Setzt außerdem ein schmales Leerzeichen vor das Wort \emph{Euro}.
+	\item Im Text in \mintinline{bash}{exercises/special-characters/special-characters.tex} findet ihr eine Reihe an Abkürzungen. Ersetzt die Leerzeichen innerhalb der Abkürzungen durch schmale Leerzeichen. Setzt außerdem ein schmales Leerzeichen vor das Wort \emph{Euro}.
 	\item Ersetzt die Bindestriche bei den Öffnungszeiten der ERBA durch Halbgeviertstriche.
 	\item Setzt beim Wort \emph{Studierendenausweis} eine ausschließliche Trennstelle nach \enquote{Studierenden-}.
 	\item Setzt die Wörter \emph{Studi-Ticket} und \emph{Studi-Karte} in Anführungszeichen. Nutzt dafür den Befehl \mintinline{latex}{\enquote}.

exercises/tables/task.tex

@@ -1,4 +1,4 @@
-Die folgende Liste zeigt ein paar Eckdaten über einige Lehrveranstaltungen an der Fakultät WIAI. Die Übersicht ist allerdings etwas unschön geraten. Wandelt deshalb die Liste in eine Tabelle mit den Spalten \emph{Name}, \emph{Kürzel} und \emph{Semester} um. Fügt zusätzlich eine \emph{zentrierte Spalte} ein, in denen ihr die Veranstaltungen nummeriert. Fügt außerdem eine Tabellenunterschrift hinzu.
+Die folgende Liste zeigt ein paar Eckdaten über einige Lehrveranstaltungen an der Fakultät WIAI. Die Übersicht ist allerdings etwas unschön geraten. Wandelt deshalb die Liste in eine Tabelle mit den Spalten \emph{Name}, \emph{Kürzel} und \emph{Semester} um. Fügt zusätzlich eine \emph{zentrierte Spalte} ein, in denen ihr die Veranstaltungen nummeriert. Fügt außerdem eine Tabellenunterschrift hinzu. Arbeitet hierfür bitte in der Datei \mintinline{bash}{exercises/tables/tables.tex}.
 
 \exercisematerial{exercises/tables/tables}
 

exercises/text-markup/task.tex

@@ -1,4 +1,4 @@
-Hebt im folgenden Text die Wörter \glqq{}Rekursion\grqq{} und \glqq{}rekursiv\grqq{} hervor und macht die URL im Text anklickbar. Natürlich könnt ihr auch die anderen Befehle, die ihr zur Textauszeichnung gelernt habt, ausprobieren. 
+Hebt im Text in der Datei \mintinline{bash}{exercies/text-markup/markup.tex} die Wörter \glqq{}Rekursion\grqq{} und \glqq{}rekursiv\grqq{} hervor und macht die URL im Text anklickbar. Natürlich könnt ihr auch die anderen Befehle, die ihr zur Textauszeichnung gelernt habt, ausprobieren. 
 
 \exercisematerial{exercises/text-markup/markup}
 

main.tex

@@ -18,6 +18,7 @@
 \tableofcontents
 \newpage
 
+\input{content/first-steps-with-latex.tex}
 \input{content/what-is-latex.tex}
 \input{content/basic-functionality.tex}
 \input{content/basic-document-structure.tex}