From 156d0efecdc5f0dee3b62c73b2e3932579e32842 Mon Sep 17 00:00:00 2001 From: Florian Knoch Date: Tue, 10 Aug 2021 22:41:48 +0200 Subject: [PATCH] Minor improvements on "Basic document structure" --- content/basic-document-structure.tex | 225 +++++++------------ exercises/basic-document-structure/task.tex | 11 +- listings/basic-document-structure/titles.tex | 6 +- 3 files changed, 91 insertions(+), 151 deletions(-) diff --git a/content/basic-document-structure.tex b/content/basic-document-structure.tex index bd8163b..f43dff8 100644 --- a/content/basic-document-structure.tex +++ b/content/basic-document-structure.tex @@ -1,46 +1,28 @@ \chapter{Basic document structure} \label{sec:basic-document-structure} -In essence, every \LaTeX{} document is composed of two parts: the first part is -the preamble. It is directly followed by the second part, the document environment. +In essence, every \LaTeX{} document is composed of two parts: +We call the first commands within our \LaTeX{} document the \emph{preamble}. +It contains global information about our document, such as the document class, the encoding, the language, the page format, and additional packages that we want to use. +The \emph{document environment}, on the other hand, contains the actual content of our document, i.\,e., the things that we will later see in our generated \acro{PDF} file. -We call the first commands within our \LaTeX{} document a \emph{preamble}. It -contains global information about our document, such as the document class, the encoding, the language, the page format, and additional packages that we want to 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. - -\Example{lst:latex-document-basic-structure}{basic-document-structure/hello-world}{basic-document-structure/hello-world_crop}{Exemplary structure of a simple \LaTeX{} document with preamble and document - environment} +\Example{lst:latex-document-basic-structure}{basic-document-structure/hello-world}{basic-document-structure/hello-world_crop}{Exemplary structure of a simple \LaTeX{} document with preamble and document environment} \section{Preamble} Let's take a closer look at the preamble. A minimal preamble should contain the following specifications: \subsection{Document class}\label{sec:document-class} -We can define a document class by using the command -\mintinline[breaklines,breakafter=\]]{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. Furthermore, 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. +We can define a document class by using the command \mintinline[breaklines,breakafter=\]]{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. +Furthermore, 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. -In addition to the standard document classes, the \acro{KOMA} script classes have developed. They provide 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{Available at: - \url{https://komascript.de/komascriptbestandteile}}. By using \acro{KOMA} -document classes, the layout of the generated \acro{PDF} document is changed. +In addition to the standard document classes, the \acro{KOMA} script classes have been developed. +They provide 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{Available at: \url{https://komascript.de/omascriptbestandteile}}. +By using \acro{KOMA} document classes, the layout of the generated \acro{PDF} document is changed. On top of that, they provide additional functionalities. The standard document classes are designed according to the American-English standards whereas \acro{KOMA} classes adhere to European norms, e.\,g., for @@ -48,26 +30,23 @@ writing letters. 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 and sets its font size -to 10\,pt\footnote{The standard font size is 12,pt.}, 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}). +\mintinline{latex}{\documentclass[10pt,a5paper,landscape]{scrartcl}}, for instance, configures a \acro{KOMA} script article and sets its font size to 10\,pt\footnote{The standard font size is 12,pt.}, 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} +\todo{Muss ``packages'' hier jetzt groß oder klein?} + \begin{minted}{latex} -\usepackage[]{} +\usepackage[]{} \end{minted} -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 in 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. + +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 formulas, lists, \textellipsis). +In order to use 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 in the Comprehensive \TeX\ Archive Network\footnote{Available at: \url{https://www.ctan.org/}}, short: \acro{CTAN}. +You can also find the documentation for the packages there. \subsection{Encoding} \begin{minted}{latex} @@ -76,141 +55,99 @@ Archive Network\footnote{Available at: \url{https://www.ctan.org/}}, short: \end{minted} One use case for packages is specifying the encoding of our \LaTeX{} document. -The character encoding\footnote{cf. - \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://en.wikipedia.org/wiki/ASCII}} -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 universal - character -encoding. +The character encoding\footnote{cf. \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://en.wikipedia.org/wiki/ASCII}} +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. -In \LaTeX{}, we need to specify two character encodings: -The input encoding (short: \mintinline{latex}{inputenc}), which refers to our -source code, and the font encoding (short: \mintinline{latex}{fontenc}), which -concerns the choice of the file that is used to portray the content within our -\acro{PDF} document, since we also need special characters -there.\footnote{Details on - \mintinline{latex}{fontenc} can be found at: - \url{https://tex.stackexchange.com/questions/108417/font-encoding-in-latex}} -\mintinline{latex}{T1} is an enconding that tries to cover most European -language with a limited number of characters. +In \LaTeX{}, we need to specify two character encodings: +The input encoding (short: \mintinline{latex}{inputenc}), which refers to our source code, and the font encoding (short: \mintinline{latex}{fontenc}), which concerns the choice of the file that is used to portray the content within our \acro{PDF} document, since we also need special characters there. +\todo{fontenc wird hier sehr umständlich beschrieben bzw. ist in dieser Detailtiefe nicht unbedingt relevant} +\footnote{Details on \mintinline{latex}{fontenc} can be found at: \url{https://tex.stackexchange.com/questions/108417/font-encoding-in-latex}} +\mintinline{latex}{T1} is an encoding that tries to cover most European languages with a limited number of characters. \subsection{Language}\label{sec:language} \begin{minted}{latex} \usepackage[ngerman]{babel} \end{minted} -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}, \textellipsis). +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}, \textellipsis). The desired language can be passed as an optional parameter. \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 \mintinline{latex}{\documentclass} command. In this case, just leave out -the -optional parameter for the language within the \mintinline{latex}{babel} -command. +Some packages require that the language is already passed as an optional parameter in the \mintinline{latex}{\documentclass} command. +In this case, just leave out the optional parameter for the language within the \mintinline{latex}{babel} command. + +We can also use multiple languages in our document. +To do so, we pass the languages, separated by commas, as an optional parameter to the \mintinline{latex}{\babel} command. +Within our document, we can switch between languages with the \mintinline{latex}{\selectlanguage{}} command. +Alternatively, foreign-language text can be declared by using the following command: -We can also use multiple languages in your document. To do so, we pass the -languages, -separated by commas, as optional parameter to the \mintinline{latex}{\babel} -command. Within your document, we can switch between languages with the -\mintinline{latex}{\selectlanguage{}} command. Alternatively,foreign-language text -can be included by using the following command: \begin{minted}{latex} \foreignlanguage{}{} \end{minted} \section{Document environment} -The actual content of the \acro{PDF} document needs to be put between -\mintinline{latex}{\begin{document}} and \mintinline{latex}{\end{document}}. +The actual content of the \acro{PDF} document needs to be put between \mintinline{latex}{\begin{document}} and \mintinline{latex}{\end{document}}. -\subsection{Continuous Text} -The easiest content that we can integrate into the document environment is -continuous -text. We can write it directly into our source code. Line breaks and multiple -spaces are ignored by \LaTeX{}. Blank lines create a new paragraph, that is -indented by default.\footnote{The automatic indentation of new paragraphs can -be prevented by using the command \mintinline{latex}{\noindent}.} -Manual line breaks can be forced with two backslashes -(\textbackslash\textbackslash). This should be avoided, though. +\subsection{Continuous text} +The easiest content that we can integrate into the document environment is continuous text. +We can write it directly into our source code. +Line breaks and multiple spaces are ignored by \LaTeX{}. +Blank lines create a new paragraph, that is indented by default. +\footnote{The automatic indentation of new paragraphs can be prevented by using the command \mintinline{latex}{\noindent}.} +Manual line breaks can be enforced with two backslashes (\textbackslash\textbackslash). +This should be avoided, though. \subsection{Comments} -Some characters are reserved for \LaTeX-specific commands, for instance, -the percent sign. Using a percent sign tells the \LaTeX{} compiler to ignore the -rest of the line, i.\,e., the text after the percent character will not appear -in the generated \acro{PDF} document. -This can be useful in order to take notes while working on a document -without affecting the document itself. This is called a comment. +Some characters are reserved for \LaTeX-specific commands, for instance, the percent sign. +Using a percent sign tells the \LaTeX{} compiler to ignore the rest of the line, i.\,e., the text after the percent character will not appear in the generated \acro{PDF} document. +This can be useful in order to take notes while working on a document without affecting the document itself. +This is called a comment. -However, if we want the percent sign to actually appear in the text, we can -achieve this by using a backslash: \mintinline{latex}{\%}. -This solution is called escaping and also works for other reserved -characters, like \#, \$, \&, \_, \{ and \}. +However, if we want the percent sign to actually appear in the text, we can achieve this by using a backslash: \mintinline{latex}{\%}. +This solution is called escaping and also works for other reserved characters, like \#, \$, \&, \_, \{ and \}. -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}.} +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{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. +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}{Heading Levels} -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-of-contents}}: +\todo{Beispiele neu generieren.} + +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-of-contents}}: \begin{minted}{latex} \section*{This section is excluded from the table of contents} \end{minted} -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: +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[Title in the TOC]{Actual Chapter Title} \end{minted} \subsection{Front matter} -A simple front 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. +A simple front 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}. -If the date is not specified by the \mintinline{latex}{\date} command, the -current date -will be inserted by default. +If the date is not specified by the \mintinline{latex}{\date} command, 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}{The Front Matter} +\Example{lst:titles}{basic-document-structure/titles}{basic-document-structure/titles_crop}{The front matter} \subsection{Indices}\label{sec:table-of-contents} -The command \mintinline{latex}{\tableofcontents} generates an automatically -numbered table of contents by making use of the above-mentioned commands for -dividing -our text into sections and chapters (this can bee seen in \cref{lst:main-file} -on \cpageref{lst:main-file}). -The numbering style and depth, and many other options can, of -course, be specified manually.\footnote{We recommend the following blogpost: - \url{https://texblog.org/2011/09/09/10-ways-to-customize-tocloflot/}} -For \LaTeX{} to create our table of contents properly, the project has to be -compiled twice. +The command \mintinline{latex}{\tableofcontents} generates an automatically numbered table of contents by making use of the above-mentioned commands for dividing our text into sections and chapters (this can bee seen in \cref{lst:main-file} on \cpageref{lst:main-file}). -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} (Graphics) and \cref{sec:tables} (Tables) for more - information on captions} +The numbering style and depth, and many other options can, of course, be specified manually. +\footnote{We recommend the following blogpost: \url{https://texblog.org/2011/09/09/10-ways-to-customize-tocloflot/}} +For \LaTeX{} to create our table of contents properly, the project has to be compiled twice. + +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} (Graphics) and \cref{sec:tables} (Tables) for more information on captions} diff --git a/exercises/basic-document-structure/task.tex b/exercises/basic-document-structure/task.tex index 30bf0f2..3ca51c2 100644 --- a/exercises/basic-document-structure/task.tex +++ b/exercises/basic-document-structure/task.tex @@ -1,7 +1,10 @@ \begin{enumerate} - \item In the directory \mintinline{latex}{exercises/basic-document-structure} you can find a file named \mintinline{latex}{document-structure.tex}. Open the file, copy its text and paste it into a new file. You can name the new file as you want. Wrap the text of your new file into a \mintinline{latex}{document} environment and add a preamble in order to be able to compile your first \LaTeX{} document. - \item Congratulations! You have created and compiled your first \LaTeX{} document. Maybe you have noticed that pargraphs within the text were created by using \mintinline{latex}{\\}. Replace the two backslashes by real paragraphs. - \item It's time to structure your first document. Use the \LaTeX{} commmands \mintinline{latex}{\section}, \mintinline{latex}{\subsection}, etc. to structure the text. Also, include a table of contents for your document. - \item Afterwards, comment out the preamble, the document environment and the table of contents. + \item In the directory \mintinline{latex}{exercises/basic-document-structure}, you can find a file named \mintinline{latex}{document-structure.tex}. Open the file, copy its text and paste it into a new file. You can name the new file as you want. Wrap the text of your new file into a \mintinline{latex}{document} environment and add a preamble in order to be able to compile your first \LaTeX{} document. + \item Congratulations! You have created and compiled your first \LaTeX{} document. Maybe you have noticed that paragraphs within the text were created by using \mintinline{latex}{\\}. Replace the two backslashes by real paragraphs. + \item It's time to structure your first document. Use the \LaTeX{} commands \mintinline{latex}{\section}, \mintinline{latex}{\subsection}, etc. to structure the text. Also, include a table of contents for your document. + \item Afterwards, comment out the preamble, the document environment, and the table of contents. \end{enumerate} + +\todo{Text übersetzen} + \exercisematerial{exercises/basic-document-structure/document-structure} diff --git a/listings/basic-document-structure/titles.tex b/listings/basic-document-structure/titles.tex index 8f602c4..360dfdd 100644 --- a/listings/basic-document-structure/titles.tex +++ b/listings/basic-document-structure/titles.tex @@ -1,9 +1,9 @@ -\documentclass[ngerman]{article} +\documentclass[english]{article} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} -\usepackage[ngerman]{babel} +\usepackage[english]{babel} -\title{Die World of Truffles} +\title{The World of Truffles} \author{Fooboar Rüssel \and Fachschaft WIAI} \date{\today}