From f3bb715c87a200081a6b4549f32ab070f9da1e24 Mon Sep 17 00:00:00 2001
From: Tobias Hilfiker <tobias@sonnenseite.ch>
Date: Sun, 12 Jan 2025 03:10:07 +0100
Subject: [PATCH] Document how to create references on environments and
 sections in text

---
 README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/README.md b/README.md
index 0016d49..8fdd566 100644
--- a/README.md
+++ b/README.md
@@ -232,3 +232,80 @@ The full table-definition defined with placeholders looks like this:
 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}. 
+```
\ No newline at end of file