commit 7b7c95fda99568b1009bd4885ad4dc326b0eb542 Author: Tobias Hilfiker Date: Sat Mar 15 07:43:49 2025 +0000 Initial commit diff --git a/.gitea/workflows/actions.yaml b/.gitea/workflows/actions.yaml new file mode 100644 index 0000000..00e3d7e --- /dev/null +++ b/.gitea/workflows/actions.yaml @@ -0,0 +1,19 @@ +name: Generate and publish Document +on: [ push, workflow_dispatch ] + +jobs: + generate-and-publish: + runs-on: ubuntu-latest + timeout-minutes: 10 + steps: + - name: Set up Git repository + uses: actions/checkout@v4 + - name: Compile LaTeX document + uses: xu-cheng/latex-action@v3 + with: + root_file: main.tex + - name: Upload PDF file + uses: actions/upload-artifact@v4 + with: + name: PDF + path: main.pdf \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..c751f0d --- /dev/null +++ b/README.md @@ -0,0 +1,478 @@ +# 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 | +|-----------------------------|--------------------------------------------------------------------------------------------------------------------------------| +| `` | Path to the image that is placed over the title/subtitle. Refer to the graphics-section for more information on graphic files. | +| `` | Main title of the document | +| `` | 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{}` | The biggest title of all. It is numbered with one number (e.g. 1 Title). | +| `\subsection{}` | This is the first subtitle. It is numbered with two numbers (e.g. 1.1 Subtitle). | +| `\subsubsection{}` | This is the second subtitle. It is numbered with three numbers (e.g. 1.1.1 Subsubtitle). | +| `\subsubsubsection{}` | This is the third subtitle. It is not numbered at all and is also not showing up in the table of contents. | + +If the section should not be numbered, you can use a * before the opening bracket. Should look like this: +`\subsection*{}`. + +## 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{}` | Formats the text inside the brackets bold. | +| `\textit{}` | Formats the text inside the brackets italic. | +| `\underline{}` | Underlines the text inside the brackets. | + +## Escaping characters + +Some characters are used as a part of a command for latex. Due to that, they need to be escaped when they should be +printed specifically. To escape a character, you use a '\\' before the character or symbol. Typical symbols you need to +escape are: + +| Symbol | Escaped | +|--------|---------| +| \\ | \\\ | + +## 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]{} + \caption{ (Quelle: \cite{})} + \label{fig:} +\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:} +``` + +## 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}{}` ➡️ 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}{} + \label{tab: | +| Image | fig: | + +```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: | + +```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}. +``` + +# Citing with BibTeX + +This template is already setup to use citations with BibTeX. To define your sources to cite from, you need to use the +`bibliography.bib` file. + +## Defining sources + +When defining sources, it's important to know, what type of source you want to create and cite. +For mor information you can visit https://www.bibtex.com/e/entry-types/. There all BibTeX types are documented. + +### Defining Web-Sources + +To define web sources, I've found the type "misc" perfect. You can always use the following template and fill in the +variables in with blanks. + +> It's **very important** to fill out the variable ``. This variable is used to reference the reference in +> the +> text to the correct BibTeX entry. + +```latex +@misc{, +author = {}, +title = {}, +date = {}, +year = {}, +urldate = {}, +note = {Abgerufen am }, +howpublished = {} +} +``` + +### Defining a Book-Source + +To define a book source, it's basically the same principle as a web source. You just got other variables / fields to +fill in. + +```latex +@book{, +author = {}, +title = {}, +publisher = {}, +year = {}, +pages = {} +} +``` + +### Defining a Newspaper-Source + +Newspaper sources work the same. You got a few more variables to fill, because there are more informations relevant. + +```latex +@article{, +author = {}, +title = {}, +journal = {}, +year = {}, +volume = {}, +number = {}, +pages = {}, +} +``` + +## Citing defined sources in LaTeX + +To cite your sources you've defined in your bibliography file, you can use the syntax of `\cite{}` as you can +see, you need your citing-id here again. This is to reference your citing in the text to the correct entry in your +bibtex-file. + +# Importing other files + +With LaTeX you can import other files (such as other LaTeX files or pdfs) into your main file. This is very useful for +attachments or external documents, which you want to include in your documentation. + +## Import .tex files + +To import .tex files, you can use `\input{}` or `\import{}`. + +## Import one .tex file + +To import a single text file, you can just use `\input{}`. + +## Import multiple .tex files after each other + +If you want to import multiple .tex files directly after each other, the syntax is a bit special. You use +`\input{}` for the first .tex file, and `\import{}` for all the following .tex files. As soon as +there is a text, heading or float (graphics/tables) between two imported .tex files, you can use `\input{}` +again. See the example below for clarification. + +```latex +\input{} +\include{} +\include{} +\include{} + + +\section{New header} +This is a text for this header. + +\input{} +``` + +## Importing external pdf's + +Importing pdfs is especially interesting for attaching sources to your documentation. The most practical way is to use a +special configuration of the `\includegraphics` command. + +```latex +\includegraphics[height=0.9\textheight]{} +``` + +With this configuration you also have enough room to add a header above the included pdf. + +### Importing a selection of pdf pages + +There is a possibility to import only two pages of a pdf into your document. Use the following configuration for this: + +```latex +\includepdf[pages={}, noautoscale=true, scale=0.9, pagecommand={\thispagestyle{fancy}}]{} +``` + +In page range its possible to use a number-range. To include from the first to for example 3rd page you can also use the +keyword `first`. The same is possible with the last page by using the keyword `last`. + +### Importing the whole multipage pdf document + +To import a full pdf document with multiple pages, you need a combination of the above standing commands. This is +because if you want to have a title above the first page, you need to make space for the title. With the +`\includegraphics` command, we make that space by making the height of the float smaller. + +So to import multiple pages of the same document, use the following syntax: + +```latex +\includegraphics[height=0.9\textheight]{} +\includepdf[pages={2-last}, noautoscale=true, scale=0.9, pagecommand={\thispagestyle{fancy}}]{} +``` + +The first command imports the first page of your pdf. The second command includes the 2nd to last page into your main +file. You can also change the page-range of the second command, in case you don't want all pages to the last inculded. + +# Create a landscape page inside a document + +To create a landscape page inside a portrait document, you can use `\begin{landscape}`. In the following example this is +explained better: + +```latex +This paragraph is still in portrait. +\pagebreak +\begin{landscape} + This paragraph is in landscape. +\end{landscape} + +This paragraph is in portrait again. +``` \ No newline at end of file diff --git a/bibliography.bib b/bibliography.bib new file mode 100644 index 0000000..e69de29 diff --git a/main.tex b/main.tex new file mode 100644 index 0000000..3f9a6d5 --- /dev/null +++ b/main.tex @@ -0,0 +1,137 @@ +% Preamble +\documentclass[11pt]{article} + +% Packages +\usepackage[utf8]{inputenc} % Inputencoding to UTF-8 +\usepackage[a4paper, top=1.85cm, bottom=2cm, left=2.5cm, right=2cm]{geometry} % Set the margin and size of a page + +\usepackage{titling} +\usepackage{textcomp} +\usepackage{wasysym} +\usepackage{array} +\usepackage{rotating} % Rotate pictures in Latex +\usepackage{smartdiagram} % Chevron-Diagrams in Latex +\usepackage{wrapfig} % Figures floating in text +\usepackage{enumerate} % Enumerations in Latex +\usepackage{capt-of} % Captions for pictures without figure-environment +\usepackage{xcolor} % Custom colors +\usepackage{subcaption} % Better cpationing of pictures and tables +\usepackage[de]{datetime2} % Get dates in german format +\usepackage{pdflscape} % Landscaped pages in Pdf +\usepackage{setspace} % Better Line spacing +\usepackage{lastpage} % Custom page numbering +\usepackage{fancyhdr} % Custom page numbering +\usepackage{tcolorbox} % In-Text Code formatting +\usepackage{pdfpages} % Import PDF into LaTeX document +\usepackage{cleveref} % Better referencing on elements +\usepackage{xspace} +\usepackage{parskip} % Stop LaTeX from making indents after every paragraph + +% UML-Diagrams in LaTeX +\usepackage{pgf-umlcd} +\usepackage{pgf-umlsd} +\usepackage{graphicx} +\usepackage{tikz} +\usepackage{lineno} +\usepackage{caption} + +% Advanced Table functions +\usepackage{tabularx} +\newcolumntype{W}{>{\hsize=1.5\hsize}X} +\newcolumntype{w}{>{\hsize=1.25\hsize}X} +\newcolumntype{m}{X} +\newcolumntype{S}{>{\hsize=.75\hsize}X} +\newcolumntype{s}{>{\hsize=.5\hsize}X} +%ATTENTION WHEN USING COLUMNS -> They have to sum up to the correct count of cols: two cols mean that the sizes have to in sum be two + +% Bibliography management +\usepackage{natbib} +\bibliographystyle{apalike} + +% Formatting for Abacus-Style +\usepackage[T1]{fontenc} +\usepackage{uarial} +\renewcommand{\familydefault}{\sfdefault} +\newcolumntype{P}[1]{>{\centering\arraybackslash}p{#1}} + +%Format titles with correct size and color +\usepackage{titlesec} +\titleformat{\section}{\Large\bfseries\color[HTML]{282828}}{\thesection}{1em}{} +\titleformat{\subsection}{\large\bfseries\color[HTML]{282828}}{\thesubsection}{1em}{} +\titleformat{\subsubsection}{\normalsize\bfseries\color[HTML]{282828}}{\thesubsubsection}{1em}{} +\newcommand{\subsubsubsection}[1]{\paragraph{#1}\mbox{}\\} + +%Recolor itemize-dots +\usepackage{enumitem} +\usepackage{kinematikz} +\setlist[itemize]{label={\color[HTML]{282828}\textbullet}, itemsep=0.1ex} + +% change commands to german +\renewcommand\contentsname{Inhaltsverzeichnis} +\renewcommand{\figurename}{Abb.} +\DTMsetdatestyle{german} +\renewcommand{\listfigurename}{Abbildungsverzeichnis} +\renewcommand{\bibsection}{\section{Literaturverzeichnis}} +\renewcommand{\listtablename}{Tabellenverzeichnis} +\renewcommand{\tablename}{Tabelle} +\crefname{table}{Tabelle}{Tabellen} +\Crefname{table}{Tabelle}{Tabellen} +\crefname{figure}{Abb.}{Abb.} +\Crefname{figure}{Abb.}{Abb.} + +% Configure page numbering & footer +\pagestyle{fancy} +\fancyhf{} +\lfoot{} +\cfoot{Seite \thepage \hspace{1pt} von~\pageref{LastPage}} +\rfoot{\today} + +\begin{document} + % Load titlepage from titlepage.tex and insert here + \input{titlepage} + \pagebreak %PAGEBREAK + + \section{Title} + + \subsection{SubTitle} + + \textbf{This is a line with bold text}\\ + \textit{This is a line with italic text}\\ + \underline{This is a line with underlined text}\\ + + \subsubsection{SubSubTitle} + + Table with two columns of different width:\\ + \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} + + The next table has equally wide columns. Additionally, it only occupies 80\% of the textwidth:\\ + \begin{center} + \begin{tabularx}{0.8\textwidth}{| m | m |} + \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} + + The next table defines multiple columns in all sizes: + + \begin{center} + \begin{tabularx}{\textwidth}{| s | S | m | w | W |} + \hline + \textbf{Header 1} & \textbf{Header 2} & \textbf{Header 3} & \textbf{Header 4} & \textbf{Header 5} \\ \hline + Content 1.1 & Content 1.2 & Content 1.3 & Content 1.4 & Content 1.5\\ \hline + Content 2.1 & Content 2.2 & Content 2.3 & Content 2.4 & Content 2.5\\ \hline + \end{tabularx} + \end{center} + + \subsubsubsection{SubSubSubTitle} + +\end{document} \ No newline at end of file diff --git a/titlepage.tex b/titlepage.tex new file mode 100644 index 0000000..09dd2d8 --- /dev/null +++ b/titlepage.tex @@ -0,0 +1,10 @@ +\begin{titlepage} + \begin{center} + \includegraphics[width=\textwidth]{} + \Huge\textbf{ } + \singlespacing + \color[HTML]{282828}\Large\textbf{} + \end{center} + + \vfill +\end{titlepage} \ No newline at end of file