From fd9336f7f5de330341979b74bd08eff0d1068e47 Mon Sep 17 00:00:00 2001 From: efradtschuk Date: Thu, 24 Jun 2021 18:09:01 +0200 Subject: [PATCH] translate basic document structure --- content/basic-document-structure.tex | 261 ++++++++++++++++++--------- 1 file changed, 173 insertions(+), 88 deletions(-) diff --git a/content/basic-document-structure.tex b/content/basic-document-structure.tex index 21921b6..d8a862b 100644 --- a/content/basic-document-structure.tex +++ b/content/basic-document-structure.tex @@ -1,133 +1,218 @@ -\chapter{Grundstruktur} +\chapter{Basic Document Structure} \label{sec:basic-document-structure} -Wie sieht so ein \LaTeX-Dokument jetzt eigentlich aus? -Im Kern besteht es immer aus zwei Teilen: einer Präambel zu Beginn sowie der unmittelbar folgenden Dokumentumgebung. -Als \emph{Präambel} bezeichnen wir die ersten Befehle eines \LaTeX-Dokumentes, mit denen globale Einstellungen wie die Dokumentklasse, die Zeichenkodierung, die Sprache und das Seitenformat festgelegt werden. -Die \emph{Dokumentumgebung} hingegen enthält den Inhalt, der später in der fertigen \acro{PDF}-Datei erscheinen soll. +How does a \LaTeX document really look like? +In essence, every \LaTeX document is composed of two parts: the first part is +the preamble which is followed by the second part, the document environment. -\Example{lst:latex-document-basic-structure}{basic-document-structure/hello-world}{basic-document-structure/hello-world_crop}{Beispielhafter Aufbau eines einfachen \LaTeX-Dokuments mit Präambel und Dokumentumgebung} +The \emph{preamble} are the first commands within our \LaTeX document and it +contains global information about our document, such as the document class that +we want to use, the encoding, the language, the page format, and additional +packages that we use. +The \emph{document environment}, on the other hand, contains the actual content +of our document, that is, the things that we will later see in our generated +\acro{PDF} file. -\section{Präambel} -Beginnen wir mit der Präambel. -Eine minimale Präambel sollte die folgenden Festlegungen treffen: +\Example{lst:latex-document-basic-structure}{basic-document-structure/hello-world}{basic-document-structure/hello-world_crop}{Beispielhafter + Structure of a simple \LaTeX document with preamble and document + environment} -\subsection{Dokumentklasse}\label{sec:document-class} -\mintinline{latex}|\documentclass[]{}| -definiert die Dokumentklasse. -Die verbreitetsten von \LaTeX\ standardmäßig unterstützten Dokumentklassen sind \mintinline{latex}{article} für kurze und \mintinline{latex}{report} für längere Dokumente, \mintinline{latex}{book} für Bücher, \mintinline{latex}{beamer}\footnote{Präsentationen in \LaTeX\ sind ein Thema für sich, auf das wir nicht näher eingehen. Bei Interesse sei diese Einführung von Overleaf empfohlen: \url{https://www.overleaf.com/learn/latex/Beamer}} für Präsentationen sowie \mintinline{latex}{letter}\footnote{Auch auf Briefe wird in diesem Skript nicht weiter eingegangen. WikiBooks gibt eine Einführung: \url{https://en.wikibooks.org/wiki/LaTeX/Letters}} für Briefe. +\section{Preamble} +Let's take a closer look at the preamble. +A minimal preamble should contain the following specifications: -Zusätzlich zu den Standard-Dokumentklassen entwickelten sich die \acro{KOMA}-Script-Klassen.\footnote{Einen umfassenden Überblick über die Möglichkeiten von \acro{KOMA}-Script gibt folgendes Handbuch: \url{https://komascript.de/~mkohm/scrguide.pdf}} -Als Alternative zum \mintinline{latex}{article} steht \mintinline{latex}{scrartcl} bereit, \mintinline{latex}{report} wird durch \mintinline{latex}{scrreport} ersetzt, \mintinline{latex}{scrbook} kann anstelle von \mintinline{latex}{book} verwendet werden und \mintinline{latex}{scrlttr2} ist als Ersatz für \mintinline{latex}{letter} entstanden. -Eine vollständige Liste aller möglichen \acro{KOMA}-Script-Dokumentklassen ist online\footnote{Erreichbar unter \url{https://komascript.de/komascriptbestandteile}} verfügbar. -Die \acro{KOMA}-Klassen ändern das Layout des fertigen \acro {PDF}-Dokuments und bringen zusätzliche Funktionalitäten mit. -Während die Standard-Klassen für den Gebrauch in Amerika gedacht sind, folgen \acro{KOMA}-Klassen europäischen Normen, etwa bei Brief"|formaten. +\subsection{Document Class}\label{sec:document-class} +We can define a document class by using the command +\mintinline{latex}|\documentclass[]{}|. The most +commonly used document classes that are supported by default are +\mintinline{latex}{article} for short documents, and \mintinline{latex}{report} +for longer ones. Futhermore you can use \mintinline{latex}{book} for books, +\mintinline{latex}{beamer}\footnote{We do not cover making presentations in + \LaTeX in this tutorial. However, if you are interested in the topic, we + recommend this introduction on Overleaf: + \url{https://www.overleaf.com/learn/latex/Beamer}} for presentations, and +\mintinline{latex}{letter}\footnote{We also do not cover letters in this + script. An introduction can be found on WikiBooks: + \url{https://en.wikibooks.org/wiki/LaTeX/Letters}} for letters. -Dem \mintinline{latex}{\documentclass}-Befehl können verschiedene optionale Parameter übergeben werden. -\mintinline{latex}{\documentclass[10pt,a5paper,landscape]{scrartcl}} etwa konfiguriert einen \acro{KOMA}-Script-Artikel mit Schriftgröße 10\,pt\footnote{Die Standardschriftgröße wäre hier 12\,pt.} auf A5-Papier\footnote{In der Voreinstellung handelte es sich um A4-Papier.} im Querformat. -Auch die Sprache kann mit übergeben werden (vgl. dazu \cref{sec:language}). +In addition to the standard document classes, the \acro{KOMA} script classes +developed over time. It offers alternatives to the document classes mentioned +above: In lieu of \mintinline{latex}{article} you can use +\mintinline{latex}{scrartcl}, \mintinline{latex}{report} is replaced by +\mintinline{latex}{scrreport}, and \mintinline{latex}{scrbook} can be used +instead of \mintinline{latex}{book}. As a replacement for +\mintinline{latex}{letter} one can use \mintinline{latex}{scrlttr2}. +A complete list of all \acro{KOMA} script classes is available +online\footnote{Erreichbar unter + \url{https://komascript.de/komascriptbestandteile}}. By using \acro{KOMA} +document classes, the layout of the generated \acro{PDF} document is changed. +On top of that, they provide additional functionality. +The standard document classes are designed according to the American-English +standards whereas \acro{KOMA} classes adhere to European norms, such as for +writing letters. -\subsection{Exkurs: Pakete} +Each \mintinline{latex}{\documentclass} command can hold optional parameters in +square brackets. +\mintinline{latex}{\documentclass[10pt,a5paper,landscape]{scrartcl}}, for +instance, configures a \acro{KOMA} script article ans specifies its font size +to 10,\pt\footnote{The standard font size is 12,pt.}, sets the page size to +A5\footnote{The default case would be A4} and the orientation of the page to +landscape. The language can be passed as an optional parameter, too (cf. +\cref{sec:language}). + +\subsection{Digression: Packages} \label{sec:packages} \begin{minted}{latex} \usepackage[]{} \end{minted} -Pakete sind \LaTeX-Erweiterungen, die zusätzliche Befehle und Funktionalitäten zur Verfügung stellen. -Es existieren verschiedene Pakete für verschiedene Anwendungsfälle (z.\,B. Formelsatz, Listen, \textellipsis). -Bevor sie verwendet werden können, müssen sie in der Präambel eingebunden werden. -Hierfür wird der obige Befehl verwendet. -Die wichtigsten \LaTeX-Pakete sind im Comprehensive \TeX\ Archive Network,\footnote{Erreichbar unter \url{https://www.ctan.org/}} kurz \acro{CTAN}, abgelegt. -Hier finden sich auch Dokumentationen zu den einzelnen Funktionalitäten. +Packages provide additional commands and functionalities that we can use within +our \LaTeX source code. There are numerous packages for different use cases +(e.\,g. typesetting forumlas, lists, \textellipsis). +In order make use of a package, it must be included within the preamble. To do +so, the above-mentioned command is used. +The most important \LaTeX packages can be found n the Comprehensive \TeX\ +Archive Network,\footnote{Available at: \url{https://www.ctan.org/}}, short: +\acro{CTAN}. You can also find the documentations for the packages there. -\subsection{Kodierung} +\subsection{Encoding} \begin{minted}{latex} \usepackage[utf8]{inputenc} -\usepackage[t1]{fontenc} +\usepackage[t1] \end{minted} -Pakete werden zum Beispiel zur Auswahl der Zeichenkodierung benötigt. -Die Zeichenkodierung\footnote{Vgl. \url{https://de.wikipedia.org/wiki/Zeichenkodierung}} entscheidet darüber, welcher Zeichensatz zur Verfügung steht. -Der Standardzeichensatz in \LaTeX\ ist \acro{ASCII}.\footnote{Vgl. \url{https://de.wikipedia.org/wiki/American_Standard_Code_for_Information_Interchange}} -Dieser amerikanische Standard enthält beispielsweise keine Umlaute und ist daher für die meisten Einsätze wenig geeignet. -Als universelle Zeichenkodierung kann \acro{UTF-8}\footnote{Vgl. \url{https://de.wikipedia.org/wiki/UTF-8}} verwendet werden. -In \LaTeX-Dokumenten sind zwei verschiedene Zeichenkodierungen von Belang. -Das Input Encoding (kurz: \mintinline{latex}{inputenc}) bezieht sich auf den Quelltext, den wir eingeben, während das Font Encoding (kurz: \mintinline{latex}{fontenc}) das fertige \acro{PDF}-Dokument beeinflusst. -Konkret beeinflusst \mintinline{latex}{fontenc} die Wahl der Schriftartdatei, die verwendet wird, um den Inhalt des Dokuments darzustellen, denn auch diese muss natürlich Sonderzeichen beinhalten.\footnote{Details zur Arbeitsweise von \mintinline{latex}{fontenc} gibt dieser Beitrag: \url{https://www.texwelt.de/fragen/5537/was-macht-eigentlich-usepackaget1fontenc}} -\mintinline{latex}{T1} ist eine Kodierung, die mit einer begrenzten Anzahl an Zeichen europäische Sprachen abzubilden versucht. +One use case for packages is specifying the encoding of our \LaTeX document. +The character encoding\footnote{Vgl. + \url{https://en.wikipedia.org/wiki/Character_encoding}} determines the +available character set. +The standard encoding in \LaTeX is \acro{ASCII}. \footnote{cf. + \url{https://de.wikipedia.org/wiki/American_Standard_Code_for_Information_Interchange}} +It is an American character encoding and therefore does, for instance, not +contain German umlauts, or other special characters, which makes it unsuitable +for most use cases. +As a consequence, \acro{UTF-8}footnote{cf. + \url{https://en.wikipedia.org/wiki/UTF-8}} can be used as a universal + character +encoding. -\subsection{Sprache}\label{sec:language} +In \LaTeX we need to specify two character encodings: +The input encoding (short: \mintinline{latex}{inputenc})) which refers to our +source code. The font encoding (short: \mintinline{latex}{fontenc}) concerncs +the choice of the file that is used to portray the content of our document +since we also need special characters there.\footnote{Details on how + \mintinline{latex}{fontenc} works can be found at: + \url{https://www.texwelt.de/fragen/5537/was-macht-eigentlich-usepackaget1fontenc}} +\mintinline{latex}{T1} is an enconding that tries to cover most European +language with a limited number of characters. + +\subsection{Language}\label{sec:language} \begin{minted}{latex} \usepackage[ngerman]{babel} \end{minted} -Das Paket \mintinline{latex}{babel} stellt sprachspezifische Informationen (z.\,B. Silbentrennung, Sonderzeichen, Wechsel zwischen Fonts, Übersetzung von Labels\footnote{Vgl. \cref{sec:references}} wie \enquote{Kapitel}, \enquote{Inhaltsverzeichnis} oder \enquote{Abbildung}) bereit. -Als optionaler Parameter kann die Sprache übergeben werden. -\mintinline{latex}{ngerman} steht hierbei für die Neue Deutsche Rechtschreibung. -Manche Pakete erfordern es, dass die Sprachangabe schon als optionaler Parameter dem \mintinline{latex}{\documentclass}-Befehl\footnote{Vgl. \cref{sec:document-class}} übergeben wird. -In diesem Fall wird der optionale Parameter beim Einbinden von \mintinline{latex}{babel} einfach weggelassen. +The package \mintinline{latex}{babel} provides language-specific information +(e.\,g. on hyphenation, special characters, changing fonts, translation of +labels\footnote{cf. \cref{sec:references}} like \enquote{Chapter}, +\enquote{Table of Contents}, or \enquote{Figure}). +The language that you want to use can be passed as an optional parameter. +Als optionaler Parameter kann die Sprache übergeben werden. +\mintinline{latex}{ngerman}, for instance, is used for the new German spelling. +Some packages require that the language is already passed as optional parameter +in the \mint{latex}{\documentclass} command. In this case, just leave aus the +optional parameter for the language within the \mintinline{latex}{babel} +command. -In einem Dokument können auch mehrere Sprachen verwendet werden. -Sie können einfach kommagetrennt als optionale Parameter aufgelistet werden. -Im Dokument kann mit dem Befehl \mintinline{latex}{\selectlanguage{}} zwischen den Sprachen umgeschaltet werden. -Fremdsprachiger Text lässt sich alternativ auch über folgenden Befehl einbinden: +You can use multiple languages in your document. To do so, pass the languages, +separated by commas, as optional parameter to the \mintinline{latex}{\babel} +command. Within your document, you can switch between langauges with the +\mintinline{latex}{\selectlanguage{}} command. Alternatively, you can +include foreign-language text by using the following command: \begin{minted}{latex} \foreignlanguage{}{} \end{minted} -\section{Dokumentumgebung} +\section{Document Environment} +The actual content of your \acro{PDF} document needs to be put between +\mintinline{latex}{\begin{document}} and \mintinline{latex}{\end{document}}. -Zwischen \mintinline{latex}{\begin{document}} und \mintinline{latex}{\end{document}} gehören die Inhalte, die tatsächlich im Dokument erscheinen sollen. +\subsection{Continuous Text} +The easiest that you can integrate into the document environment is continuous +text. You can directly write it into your source code. Line breaks and multiple +spaces are ignored by \LaTeX. Blank lines create a new paragraph, which are +indented by default. \footnote{The automatic indentation of new paragraphs can +be prevented by using the command \mintinline{latex}{\noindent}.} +Manual linebreaks can be forced with two backslashes +(\textbackslash\textbackslash). This should be avoided, though. -\subsection{Fließtext} -Der einfachste Inhalt der Dokumentumgebung ist Fließtext. -Er kann direkt in den Quelltext geschrieben werden. -Zeilenumbrüche und zu mehreren auftretende Leerzeichen werden dabei ignoriert. -Leerzeilen erzeugen einen neuen Absatz, der standardmäßig mit einem Einzug beginnt.\footnote{Der Befehl \mintinline{latex}{\noindent} verhindert dies.} -Manuelle Umbrüche können mit zwei Backslashes (\textbackslash\textbackslash) erzwungen werden. -Dies sollte jedoch vermieden werden. +\subsection{Comments} +Some characters are reserved for \LaTeX-specific commands. By using a percent +sign, for instance, the rest of the line is going to be ignroed by the +compiler, i.\,e. the text will not appear in your generated \acro{PDF} document. +This can be useful in order to take notes while working on your document +without affecting the actual document. This is called a comment. -\subsection{Kommentare} -Einige Zeichen sind für besondere Funktionen reserviert. -So bewirkt ein Prozent-Zeichen beispielsweise, dass der Rest einer Zeile vom Compiler ignoriert wird. -Der Text erscheint also nicht im fertigen \acro{PDF}-Dokument. -Dies kann nützlich sein, um während der Bearbeitung Notizen festzuhalten, ohne Einfluss auf das fertige Dokument zu nehmen. -Wir sprechen hier von einem Kommentar. +However, if you want the percent sign to actually appear in your text, you can +achieve this by using a backslash: \mintinline{latex}{\%}. +This solution is also called escaping and also works for other reserved +characters, like \#, \$, \&, \_, \{ and \}. -Falls tatsächlich ein Prozentzeichen erscheinen soll, könnt ihr dies durch einen Backslash erreichen: \mintinline{latex}{\%}. -Diese Lösung, die auch als Escaping bezeichnet wird, funktioniert auch für die Zeichen \#, \$, \&, \_, \{ und \}. -Für den Backslash muss der Befehl \mintinline{latex}{\textbackslash} verwendet werden.\footnote{Eine Übersicht weiterer Sonderzeichen ist im zugehörigen \cref{sec:special-characters} zu finden.} +In order to escape the backslash, the command +\mintinline{latex}{\textbackslash} must be used.\footnote{An overview of +additional special characters can be found in \cref{sec:special-characters}.} -\subsection{Abschnitte und Kapitel} -Texte werden durch Überschriften in Abschnitte und Kapitel unterteilt. -Immer nutzbar sind die in \cref{lst:headlines} dargestellten Befehle. +\subsection{Sections and Chapters} +Continuous text can be structured by headings that divide the document into +sections and chapters. Needless to say, \LaTeX provides us with commands for +that. +The commands that are depicted in \cref{lst:headlines} can be used with any +document class. \Example{lst:headlines}{basic-document-structure/headlines}{basic-document-structure/headlines_crop}{Überschriftenebenen} -Je nach Dokumentklasse sind außerdem \mintinline{latex}{\chapter{Kapitel}} und \mintinline{latex}{\part{Teil}} verfügbar -- beispielsweise in Büchern. -Mit Sternchen fallen bei allen diesen Befehlen die Nummerierung und der Eintrag im Inhaltsverzeichnis\footnote{Vgl. \cref{sec:table-of-contents}} weg: +Depending on your specified document class the commands +\mintinline{latex}{\chapter{Chapter}} and \mintinline{latex}{\part{Part}} are +additionally available -- for instance in books. +You can mark the command with an asterisk if you want to omit the numbering of +a section and exclude it from the table of contents\footnote{cf. +\cref{sec:table}}: \begin{minted}{latex} -\section*{Kommt nicht im Inhaltsverzeichnis vor} +\section*{This section is excluded from the table of contents} \end{minted} -Ein alternativer Titel im Inhaltsverzeichnis kann als optionaler Parameter in eckigen Klammern zwischen dem Befehl und dem eigentlichen Titel angegeben werden. +An alternative title for the table of contents can be declared as an optional +parameter in square brackets between the command and the actual title. \begin{minted}{latex} -\section[Titel im Verzeichnis]{Kapitelüberschrift} +\section[Title in the TOC]{Actual Chapter Title} \end{minted} -\subsection{Titelei} -Ein einfacher Titel lässt sich im Dokument mit dem Befehl \mintinline{latex}{\maketitle} erzeugen. -Die Werte für die Einträge müssen in der Präambel festgelegt werden. -Mehrere Autoren werden dabei mit \mintinline{latex}{\and} verbunden. -Fehlt der Befehl \mintinline{latex}{\date}, wird per default das aktuelle Datum gesetzt. -Die genaue Gestaltung hängt von der verwendeten Dokumentklasse ab. +\subsection{Front Matter} +A simple font matter can be created by using the command +\mintinline{latex}{\maketitle}. The values that get inserted into the front +matter must be specified within the preamble. +Multiple authors are joined by \mintinline{latex}{\and}. +Ein einfacher Titel lässt sich im Dokument mit dem Befehl +\mintinline{latex}{\maketitle} erzeugen. +If the date is not specified by \mintinline{latex}{\date}, the current date +will be inserted by default. +The design of the front matter depends on the specified document class. -\Example{lst:titles}{basic-document-structure/titles}{basic-document-structure/titles_crop}{Die Titelei} +\Example{lst:titles}{basic-document-structure/titles}{basic-document-structure/titles_crop}{Die + Titelei} -\subsection{Verzeichnisse}\label{sec:table-of-contents} +\subsection{Indices}\label{sec:table-of-contents} +If you structure your document with the above-mentioned commands for headings, +the command \mint{latex}{\tableofcontents} generates a automatically numbered +table of contents of it (like in \cref{lst:main-file} on +\cpageref{lst:main-file}). -Aus allen mit den oben genannten Befehlen eingefügten Abschnitten fügt der Befehl \mintinline{latex}{\tableofcontents} ein automatisch nummeriertes Inhaltsverzeichnis zusammen (wie zum Beispiel in \cref{lst:main-file} auf \cpageref{lst:main-file} zu sehen). -Die Aufzählungszeichen, die Tiefe der Aufzählung und viele weitere Gestaltungselemente sind frei anpassbar.\footnote{Ein empfehlenswerter Blogpost hierzu ist unter \url{https://texblog.org/2011/09/09/10-ways-to-customize-tocloflot/} verfügbar.} -Damit \LaTeX\ das Inhaltsverzeichnis vollständig baut, muss das Projekt zweimal kompiliert werden. +The numbering style, the depth of the numbering and many other options can, of +course, be adapted. \footnote{We recommend the following blogpost: + \url{https://texblog.org/2011/09/09/10-ways-to-customize-tocloflot/}} +For \LaTeX to create your table of contents, the project has to be compiled +twice. -Neben dem Inhaltsverzeichnis stehen auch eine \mintinline{latex}{\listoffigures} (Abbildungsverzeichnis) und eine \mintinline{latex}{\listoftables} (Tabellenverzeichnis) zur Verfügung. -Aufgeführt werden jeweils die Bild- oder Tabellenunterschriften.\footnote{Siehe hierzu \cref{sec:graphics} (Grafiken) und \cref{sec:tables} (Tabellen).} +Besides the table of contents, you can also generate a +\mintinline{latex}{\listoffigures} (list of figures) and a +\mintinline{latex}{\listoftables} (list of tables). The captions of your +figures and tables will appear within those indices.\footnote{cf. + \cref{sec:graphics} (Grafiken) and \cref{sec:tables} (Tabellen) for more + information on this.}