311 lines
15 KiB
Markdown
311 lines
15 KiB
Markdown
# Initial Information
|
||
|
||
This is a LaTeX Template Repo to create other Documents. The contents include:
|
||
|
||
| Filename | Description |
|
||
|--------------------|----------------------------------------------------------------------------------------|
|
||
| `main.tex` | Main LaTeX File where the contents of the document belong into |
|
||
| `bibliography.bib` | Bibliography list for citing with BibTeX |
|
||
| `titlepage.tex` | Title-Page of the Document as an own Folder. So that it can be designed independently. |
|
||
|
||
Use this Template to create your own repo with the starter-documents and an integrated Action to build and publish your
|
||
LaTeX-Projects on Push.
|
||
|
||
# Files
|
||
|
||
Here, the various contents and variables of the files get explained. This is especially important for the initial setup
|
||
of your project.
|
||
|
||
## Titlepage.tex
|
||
|
||
The Titlepage-File defines (as the name implies) the layout and contents of the titlepage. It gets imported into the
|
||
main.tex document, that you only get one PDF with all the contents in it.
|
||
|
||
### Placeholders
|
||
|
||
The File holds multiple placeholders, which should be replaced with the actual value.
|
||
|
||
| Placeholder | Meaning |
|
||
|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------|
|
||
| `<TITLEPAGE_GRAPHICS_PATH>` | Path to the image that is placed over the title/subtitle. Refer to the graphics-section for more information on graphic files. |
|
||
| `<MAIN_TITLE>` | Main title of the document |
|
||
| `<SUBTITLE>` | Subtitle of the document |
|
||
|
||
# Basic LaTeX formatting
|
||
|
||
LaTeX enables you to format your text as you wish, probably with much more flexibility than e.g. Microsoft Word. There
|
||
are a few commands (explained below) which you should know before starting with your LaTeX file.
|
||
|
||
## Creating titles
|
||
|
||
These commands are used to create different titles. The titles in this document are automatically numbered and are
|
||
automatically styled correctly.
|
||
|
||
| Command | Explanation |
|
||
|-----------------------------------|------------------------------------------------------------------------------------------------------------|
|
||
| `\section{<YOUR_TITLE>}` | The biggest title of all. It is numbered with one number (e.g. 1 Title). |
|
||
| `\subsection{<YOUR_TITLE>}` | This is the first subtitle. It is numbered with two numbers (e.g. 1.1 Subtitle). |
|
||
| `\subsubsection{<YOUR_TITLE>}` | This is the second subtitle. It is numbered with three numbers (e.g. 1.1.1 Subsubtitle). |
|
||
| `\subsubsubsection{<YOUR_TITLE>}` | This is the third subtitle. It is not numbered at all and is also not showing up in the table of contents. |
|
||
|
||
## Formatting text
|
||
|
||
The following commands are used to format normal paragraphs. However, most commands can be used in other environments (
|
||
e.g. tables) as well.
|
||
|
||
| Command | Explanation |
|
||
|----------------------|----------------------------------------------------------------------------------------------------------------------------------|
|
||
| `\\` | Creates a new line. Its usage is only necessary when you explicitly want a newline. LaTeX generally does the line break for you. |
|
||
| `\textbf{<TEXT>}` | Formats the text inside the brackets bold. |
|
||
| `\textit{<TEXT>}` | Formats the text inside the brackets italic. |
|
||
| `\underline{<TEXT>}` | Underlines the text inside the brackets. |
|
||
|
||
## Bulletpoints and Enumerations
|
||
|
||
### Bulletpoints
|
||
|
||
To create a list of bulletpoints, we use an itemized environment. Inside it, we can use `\item` to create a new point.
|
||
|
||
```latex
|
||
\begin{itemize}
|
||
\item first point
|
||
\item second point
|
||
\item third point
|
||
\end{itemize}
|
||
```
|
||
|
||
Inside an itemized environment, you don't need to do line breaks manually. With each item, you start a new line.
|
||
|
||
### Enumerations
|
||
|
||
Enumerations work nearly the same as bulletpoints. They just use the enumerate environment instead of the itemized
|
||
environment. As with bulletpoints, you can use `\item` to create a new item in the list.
|
||
|
||
```latex
|
||
\begin{enumerate}
|
||
\item first numbered item
|
||
\item second numbered item
|
||
\item third numbered item
|
||
\end{enumerate}
|
||
```
|
||
|
||
## Specials
|
||
|
||
Here are some special options to format the text.
|
||
⚠️ In general, these commands should not be used. There are a few exceptions where it's okay to use them.⚠️
|
||
|
||
| Command | Explanation |
|
||
|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||
| `\noindent` | Used before a paragraph. It disables the indentation of the whole paragraph, if there is no title before it. |
|
||
| `\pagebreak` | As the name of the command implies, it creates a new pagebreak. This is pretty useful, if you want to finally format your document. It does break the formatting which the compiler does and messes with the whole formatting in a way that you can't control. **Only use with absolute caution!** |
|
||
| `\newline` | This command creates a new line, on which the text is continued. So it does the same as `\\` but just that it does not mess with some things (e.g. tables or escaping special characters instead of breaking). |
|
||
|
||
# Use of Graphics
|
||
|
||
Using graphics in LaTeX is not difficult. It's best practice to create a new subfolder (e.g. `graphics`) in your project
|
||
to store all the graphics. To embed a graphic into your document, two steps are required. First, you need to insert the
|
||
graphic with all information associated with it into the document. Idealy you position this part near the position in
|
||
the real document.
|
||
> ⚠️ Attention:
|
||
> If used correctly, the graphic is placed into the document by the compiler. You ***do not need to*** position the
|
||
> graphic yourself.
|
||
|
||
## Importing graphics into LaTeX
|
||
|
||
```latex
|
||
\begin{figure}
|
||
\centering
|
||
\includegraphics[width=0.8\linewidth]{<YOUR_GRAPHICS_PATH>}
|
||
\caption{<CAPTION_TEXT> (Quelle: \cite{<CITE_REFERENCE>})}
|
||
\label{fig:<FIGURE_ID_NAME>}
|
||
\end{figure}
|
||
```
|
||
|
||
The example places the Figure in the middle ( `\centering`).
|
||
It's width is defined as 80% of the linewidth (linewidth equals the width of a text-line). The percentage-value can be
|
||
changed as needed. If the width should be 100% of the line, you just use `\linewidth`.
|
||
|
||
## Referencing graphics in the text
|
||
|
||
It's important that the graphics that you use are referenced in the text, so that LaTeX can determine where the graphic
|
||
should be positioned in the document. To reference a graphic in the text, use the following syntax:
|
||
|
||
```latex
|
||
\cref{fig:<FIGURE_ID_NAME>}
|
||
```
|
||
|
||
## Special graphic-options
|
||
|
||
> **⚠️USE THESE WITH EXTREME CAUTION⚠️**
|
||
|
||
- `\begin{figure} [h]` ➡️ the `[h]` means that the figure should be placed exactly here in the document. You override
|
||
the compiler with this setting, so you should only use it if really necessary.
|
||
- `\captionof{figure}{<CAPTION>}` ➡️ Sometimes you need to use `\captionof` instead of `\caption` to get the caption
|
||
below a figure working.
|
||
|
||
# Use of Tables
|
||
|
||
In this template some preparations are done, that creating tables is not that difficult.
|
||
|
||
## Column width
|
||
|
||
There are five different widths defined for the table columns. The width gets calculated from the value `m`, so a
|
||
column-width of `m` equals 100% relative width.
|
||
|
||
| letter defining width | relative percentage to `m` |
|
||
|-----------------------|----------------------------|
|
||
| `W` | 150% |
|
||
| `w` | 125% |
|
||
| `m` | 100% |
|
||
| `S` | 75% |
|
||
| `s` | 50% |
|
||
|
||
## Defining a basic table
|
||
|
||
To define a table, we start by defining a centred (you probably want your tables centred on the page) block. Then we
|
||
define a `tabularx` environment, which gives us the functionality of the table itself. In there, we need to define our
|
||
columns and can define the contents of the table. An example-definition of a table looks like this:
|
||
|
||
```latex
|
||
\begin{center}
|
||
\begin{tabularx}{\textwidth}{| S | w |}
|
||
\hline
|
||
\textbf{Header 1} & \textbf{Header 2} \\ \hline
|
||
Content 1.1 & Content 1.2 \\ \hline
|
||
Content 2.1 & Content 2.2 \\ \hline
|
||
\end{tabularx}
|
||
\end{center}
|
||
```
|
||
|
||
In the example above, the table is defined with a `S` and a `w` column width. Due to the fact, that there are two
|
||
columns defined, the sum of all width-percentage-values need to get to 200% (per defined column 100% width, so with two
|
||
columns 200%).
|
||
In this case we have a 75% width column (defined with `S`) and a 125% width column (defined with `w`). In sum, we get to
|
||
200%. **If this calculation is not done correctly, the table will not be shown correctly in the generated PDF.**
|
||
|
||
### Table width
|
||
|
||
The table width is determined by the first argument of `tabularx`. In the example above, the table-width is defined as
|
||
the textwidth. If you want 80% of the textwidth, you can do that by typing `0.8\textwidth`.
|
||
|
||
### Defining columns
|
||
|
||
To define columns, we use the second argument of `tabularx`. To get vertical lines in the table, they need to be defined
|
||
in this argument.
|
||
The left line (created by AltGR + 7) represents the left table-border.
|
||
Then there is a space, following the letter for the column width (as seen in the last chapter).
|
||
After another space, the seperator between the two columns follows.
|
||
The same is repeated for the second column and it's border to the right of it.
|
||
|
||
### \\\ \hline?
|
||
|
||
\\\ creates a new line, as learned in the chapter [Basic LaTeX formatting](#Basic-LaTeX-formatting). It does the same in
|
||
tables. Just that you only want to generate a new line in tables, when you're actually at the end of the line.
|
||
|
||
The command `\hline` creates a horizontal line. If you don't write that command (and just break the line to the next
|
||
one) you don't get a delimiting line between the lines.
|
||
|
||
### Separating column content
|
||
|
||
To separate the contents of two different columns, the `&` symbol is used. You can just place it wherever you need the
|
||
seperation of the contents to happen.
|
||
|
||
## Defining a table with all properties
|
||
|
||
In the previous chapter, you learned how to define a basic table. To define a full table (as probably needed in your
|
||
documentation) you need to add a few lines of LaTeX.
|
||
The full table-definition defined with placeholders looks like this:
|
||
|
||
```latex
|
||
\begin{center}
|
||
\begin{tabularx}{\textwidth}{| S | w |}
|
||
\hline
|
||
\textbf{Header 1} & \textbf{Header 2} \\ \hline
|
||
Content 1.1 & Content 1.2 \\ \hline
|
||
Content 2.1 & Content 2.2 \\ \hline
|
||
\end{tabularx}
|
||
\captionof{table}{<TABLE_CAPTION>}
|
||
\label{tab:<TABLE_ID_NAME}
|
||
\end{center}
|
||
```
|
||
|
||
Here, we also have the table captioned (which enables us to create a table-directory) and we also gave the table a
|
||
label. The label is (as with graphics) important to reference it in the text, that it can be placed correctly by the
|
||
compiler.
|
||
|
||
# Reference tables and images in text
|
||
|
||
With the compiler in LaTeX you get the best results with the placement of pictures and tables, if you reference them in
|
||
the text they belong to. The compiler then places them near that text automatically. You can also reference to a
|
||
section, in which case the title of the section gets automatically updated.
|
||
|
||
## Referencing tables & images
|
||
|
||
The process of referencing tables and images is the same for both of them. In the preceeding chapters of this manual we
|
||
have seen the labelling process for tables and images.
|
||
|
||
### Labelling tables & images
|
||
|
||
To create a reference, the target-element has to be given an id first. That id is called label in LaTeX. Its best
|
||
practice, to label tables and images differently. I personally like to use the following prefixes for tables and images,
|
||
followed by a short 1-3 word description of the image or table.
|
||
|
||
| type | label |
|
||
|-------|----------------------------|
|
||
| Table | tab:<DESCRIPTION_OF_TABLE> |
|
||
| Image | fig:<DESCRIPTION_OF_IMAGE> |
|
||
|
||
```latex
|
||
\begin{figure}
|
||
\centering
|
||
\includegraphics[width=\linewidth]{graphics/examplegraphic}
|
||
\label{fig:exampleimage}
|
||
\end{figure}
|
||
|
||
\begin{center}
|
||
\begin{tabularx}{\textwidth}{| m | m |}
|
||
\hline
|
||
\textbf{Header 1} & \textbf{Header 2} \\ \hline
|
||
Content 1.1 & Content 1.2 \\ \hline
|
||
\end{tabularx}
|
||
\label{tab:exampletable}
|
||
\end{center}
|
||
```
|
||
|
||
### Referencing on tables & images in the text
|
||
|
||
To reference on tables and images in the text, we use the command `cref`. It takes the label of the element you want to
|
||
reference as a parameter. So an example-usage in a text would be the following:
|
||
|
||
```latex
|
||
This is a text example. You can see its usage in the image \cref{fig:exampleimage}.
|
||
You can also view the table \cref{tab:exampletable} for the full command reference.
|
||
```
|
||
|
||
## Referencing sections
|
||
|
||
Referencing sections works basically the same way as referencing tables or images. It also uses labels on the sections,
|
||
but it does not use `cref` to create the reference. Instead we just use `ref`.
|
||
|
||
### Labelling sections
|
||
|
||
For labelling sections, I also like to use a prefix. I use the prefix `sec:` for sections. After the prefix, there is a
|
||
short description of the section (or the whole title if it's just 1-3 words) to identify the section uniquely.
|
||
|
||
| type | label |
|
||
|----------|------------------------------|
|
||
| sections | sec:<DESCRIPTION_OF_SECTION> |
|
||
|
||
```latex
|
||
\section{This is a section.}
|
||
\label{sec:examplesection} This is the text that is displayed directly after the title.
|
||
```
|
||
|
||
### Referencing a section in the text
|
||
|
||
As mentioned, we reference a section similarly to tables and images. We just use another command to reference it. We use
|
||
`\ref`, which takes the label of the section as an argument.
|
||
|
||
```latex
|
||
This is a text. In this text we reference to the chapter \ref{sec:examplesection}.
|
||
``` |