diff --git a/README.md b/README.md
index 9258300..156ffe0 100644
--- a/README.md
+++ b/README.md
@@ -1,144 +1,143 @@
+# A LaTeX Cookbook
+
[](https://forthebadge.com)
[](https://forthebadge.com)
-# A LaTeX Cookbook, git and Continuous Delivery
+---
> [Remember, a few hours of trial and error can save you several minutes of looking at the README.](https://twitter.com/iamdevloper/status/1060067235316809729)
-This [repository](https://collaborating.tuhh.de/alex/latex-git-cookbook)
-contains two documents:
+---
-1. This README in Markdown format.
- Using `pandoc` with the *Eisvogel* template (more on that later), it is converted
- into a PDF and made available for download (see also the
- [badge](https://docs.gitlab.com/ee/user/project/badges.html) on top of the
- [project homepage](https://collaborating.tuhh.de/alex/latex-git-cookbook)):
+This repo contains a [LaTeX](https://en.wikipedia.org/wiki/LaTeX) [document](cookbook.tex), usable as a cookbook (different "recipes" to achieve various things in LaTeX) and also as a template.
+The resulting PDF covers LaTeX-specific topics and instructions on compiling the LaTeX source using Docker.
+It is available for [**download**](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/jobs/artifacts/master/raw/cookbook.pdf?job=tex).
- [](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/jobs/artifacts/master/raw/README.pdf?job=README.pdf)
+This very README is also made available for [download as a PDF](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/jobs/artifacts/master/raw/README.pdf?job=README.pdf), converted from Markdown using [pandoc](https://pandoc.org/) with the [*Eisvogel*](https://github.com/Wandmalfarbe/pandoc-latex-template) template.
- **The README covers git and Continuous Delivery.**
-2. A [LaTeX document](cookbook.tex), usable as a cookbook (different "recipes" to
- achieve various things in LaTeX) and also as a template.
+## git
- The LaTeX Cookbook PDF covers LaTeX-specific topics and instruction on compiling the
- LaTeX source using Docker.
- It is also available for download:
+[Version control](https://www.atlassian.com/git/tutorials/what-is-version-control#benefits-of-version-control) (we use, like virtually everyone nowadays, [git](https://thenewstack.io/tutorial-git-for-absolutely-everyone/)) is very important: it allows to roll back to healthy versions of projects, and it goes hand in hand with collaboration ([GitLab](https://about.gitlab.com/)/[GitHub](https://github.com/)) as well as backups ([remotes](https://www.atlassian.com/git/tutorials/syncing)).
- [](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/jobs/artifacts/master/raw/cookbook.pdf?job=tex)
+## Advantages
-## git
+Some advantages of using version control (specifically, git, but most is applicable to others as well) are lined out below.
-That being said, onto [git](https://thenewstack.io/tutorial-git-for-absolutely-everyone/).
-This README will not be exhaustive; there are numerous great tools to learn git out
-there.
-This is just a brief introduction.
-Eventually, following all the steps, a number of advantages will come to light:
+### [SSOT](https://en.wikipedia.org/wiki/Single_source_of_truth) (*Single Source Of Truth*)
-- [SSOT](https://en.wikipedia.org/wiki/Single_source_of_truth): a *Single Source Of Truth*
- for data.
- No more file trees looking like this:
+No more file trees looking like:
- ```text
- directory
- │ a.txt
- │ help.me.please
- │ Important-Document_2018_version1.pdf
- │ Important-Document_2018_version2.pdf
- │ Important-Document_2018_version3_final.pdf
- │ Important-Document_2018_version3_final_really.pdf
- │ Important-Document_2018_version3_final_really_I-promise.pdf
- │ Important-Document_2018_versionA.pdf
- │ Important-Document_2019-03-56.pdf
- │ Important-Document_2019-03-56_corrections_John-Doe.pdf
- │ Important-Document_2019-03-56_corrections_John-Doe_v2.pdf
- │ invoice.docx
- │ test - Copy (2).tex
- │ test - Copy.tex
- │ test.tex
- │
- └───old_stuff
- Screenshot 1999-09-03-15-23-15(1).bmp
- Screenshot 1999-09-03-15-23-15(2).bmp
- Screenshot 1999-09-03-15-23-15(3).bmp
- Screenshot 1999-09-03-15-23-15(3)_edited.bmp
- Screenshot 1999-09-03-15-23-15.bmp
- ```
+```text
+directory
+│ a.txt
+│ help.me.please
+│ Important-Document_2018_version1.pdf
+│ Important-Document_2018_version2.pdf
+│ Important-Document_2018_version3_final.pdf
+│ Important-Document_2018_version3_final_really.pdf
+│ Important-Document_2018_version3_final_really_I-promise.pdf
+│ Important-Document_2018_versionA.pdf
+│ Important-Document_2019-03-56.pdf
+│ Important-Document_2019-03-56_corrections_John-Doe.pdf
+│ Important-Document_2019-03-56_corrections_John-Doe_v2.pdf
+│ invoice.docx
+│ test - Copy (2).tex
+│ test - Copy.tex
+│ test.tex
+│
+└───old_stuff
+ Screenshot 1999-09-03-15-23-15(1).bmp
+ Screenshot 1999-09-03-15-23-15(2).bmp
+ Screenshot 1999-09-03-15-23-15(3).bmp
+ Screenshot 1999-09-03-15-23-15(3)_edited.bmp
+ Screenshot 1999-09-03-15-23-15.bmp
+```
- Instead, there is one *working copy* looking like this:
+Instead, there is one [*working copy*](https://stackoverflow.com/questions/36201342/git-where-exactly-is-the-working-directory) looking like:
- ```text
- directory
- │ .git (a hidden directory)
- │ a.txt
- │ Important-Document.pdf
- │ Properly-Named-Invoice.docx
- ```
+```text
+directory
+│ .git (a hidden directory)
+│ a.txt
+│ Important-Document.pdf
+└───Properly-Named-Invoice.docx
+```
- assuming that `a.txt` is actually needed.
- **All the old junk and redundant copies have been pruned**.
- However, **nothing was lost**.
- The entire history is contained in [**git**](https://en.wikipedia.org/wiki/Git), a *Version Control System*.
- The history is readily summoned anytime, if so required.
- Git calls this its *log*.
- Git works best (some would say only) on text-based files, but it can deal with images, PDFs *etc.*, too.
-
- The history and everything else git needs is contained in its `.git` directory, which is hidden on both Linux and Windows.
- Everything else in `directory`, so in this case `a.txt`, `Important-Document.pdf` and `Properly-Named-Invoice.docx`, is accessible as usual.
- **There is no difference to how you would normally work with these files.**
- They are on your local disk.
- Together, they are called the *working tree*.
-
- Therefore (provided that git is used correctly):
-
- 1. Duplicate files are gone,
- 2. The art of cumbersome file naming will finally be forgotten,
- 3. Old stuff can be safely deleted; this cleans up the working tree and makes it clear which files are no longer needed.
- Only the currently needed files are visible, the rest is (retrievable!) history.
-- File versioning and the ability to exactly match outputs (PDFs) to the source code
- that generated them.
-- Accelerated bug fixing through `git bisect`, a binary search algorithm that helps
- pinpoint commits (stages of development) that introduced regressions.
-- Collaboration: each contributor has a version of the source on their local machine.
- Adjustments are made there, and sent to a central, online repository if they are
- considered ready to be published.
- Git can also be used in a distributed fashion (its original strong suit), but we
- assume a remote repository on GitLab (which is very much similar to GitHub).
- Developers can then also fetch the latest changes from the remote and incorporate
- them into their local copy.
-
- Do not confuse GitHub, GitLab and others with the tool itself, git.
- Microsoft's GitHub is not synonymous to git.
- A crude, mostly wrong analogy would be: OneDrive is the platform you do collaboration,
- version control and sharing on.
- This is like GitHub (GitLab, ...).
- Office programs like Microsoft Word are used to create original content.
- This is like source code, as created in some editor of your choice.
- Word's built-in revision history, in conjunction with the *process* of naming files,
- for example `2020-05-13_Invoice_John-Doe-Comments_Final.docx`
- ([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) oh yeah baby),
- would be git.
- It "only" does the version control, but is not a *platform* for source code.
-- The remote repository also serves as a back-up solution.
- So do all the distributed local copies.
- At all points, there will be a workable copy *somewhere*.
- In general, git makes losing data extremely hard.
- **If**, or rather *when*, you *do* get into a fight with git about merging, pulling,
- rebasing, conflicts and the like, think of it as git protecting you and your work.
- Often, the reason for git "misbehaving" and making a scene is because it flat-out
- refuses to conduct an operation that would destroy unsaved changes.
- In the long run, this behavior is the desired one, as opposed to losing unsaved
- (in the git-lingo: uncommitted) data.
-
-### Getting Started
+assuming that `a.txt` is actually needed.
+**All the old junk and redundant copies have been pruned**.
+However, **nothing was lost**.
+The entire history is contained within [git](https://en.wikipedia.org/wiki/Git).
+The history is readily summoned anytime, if so required.
+Git calls this its [*log*](https://www.atlassian.com/git/tutorials/git-log).
+Git works best (some would say only) on text-based files, but it can deal with images, PDFs *etc.*, too.
-Download for [Windows here](https://git-scm.com/download/win).
-Install it and spam *Next* without reading the installation and warning prompts,
-as you always do.
+The history and everything else git needs is contained in its `.git` directory, which is hidden on both Linux and Windows.
+**Do NOT mess with this directory directly: interact with git only through its command interface**.
+Everything else in `directory`, so in this case `a.txt`, `Important-Document.pdf` and `Properly-Named-Invoice.docx`, is accessible as usual.
+**There is no difference to how you would normally work with these files.**
+They are on your local disk.
+Together, they are called the *working tree*.
+
+Therefore (provided that git is used correctly):
+
+1. duplicate files are gone,
+2. the art of cumbersome file naming will finally be forgotten,
+3. old stuff can be safely deleted; this cleans up the working tree and makes it clear which files are no longer needed.
+ Only the currently needed files are visible, the rest is (retrievable!) history.
+
+### File Versioning
+
+Everything is versioned.
+Outputs (e.g. PDFs in the case of LaTeX) can be matched to the source code that generated them exactly.
+Important states can be [tagged](https://www.atlassian.com/git/tutorials/inspecting-a-repository/git-tag) and found again easily.
+
+### Collaboration
+
+Each contributor has a version of the source on their local machine.
+Adjustments are made there, and sent to a [central, online repository](https://www.atlassian.com/git/tutorials/syncing) if they are considered ready to be published.
+Git can also be used in a distributed fashion (its original strong suit), but we assume a remote repository on a platform like GitLab or GitHub.
+Developers can then also fetch the latest changes from the remote and incorporate them into their local copy.
+
+Do not confuse GitHub, GitLab and others with the tool itself, git.
+Microsoft's GitHub is not synonymous to git.
+A crude, mostly wrong analogy would be: OneDrive is the platform you do collaboration, version control and sharing on.
+This is like GitHub (GitLab, ...).
+Office programs like Microsoft Word are used to create original content.
+This is like source code, as created in some editor of your choice.
+Word's built-in revision history, in conjunction with the process of naming files, for example `2020-05-13_Invoice_John-Doe-Comments_Final.docx` ([ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) oh yeah), would be git.
+It "only" does the version control, but is not a *platform* for source code.
+
+### Backups
+
+The remote repository also serves as a back-up solution.
+So do all the distributed local copies.
+At all points, there will be a workable copy *somewhere*.
+In general, git makes losing data extremely hard.
+When (not if!) you get into a fight with git about merging, pulling, rebasing, conflicts and the like, think of it as git protecting you and your work.
+Often, the reason for git "misbehaving" and making a scene is because it flat-out refuses an operation that would destroy unsaved changes.
+In the long run, this behavior is the desired one, as opposed to losing unsaved (git lingo: *uncommitted*) data.
-For Linux, `apt update && apt install git` or whatever.
+### Branching
+
+Branches, essentially deviating paths in development, are at the heart of git.
+In git, they are lightweight constructs and not as heavy as in for example SVN.
+You can experiment liberally using [branching](https://www.atlassian.com/git/tutorials/using-branches), combine and split ideas, files etc.
+
+### Bug Fixing
+
+Bug fixing can be accelerated through `git bisect`, a search algorithm that helps pinpoint commits (stages of development) that introduced regressions.
+If you know that something is broken today but worked two weeks ago, and there are say 80 commits in your history since then, [bisection](https://interrupt.memfault.com/blog/git-bisect) helps you find the culprit much, much faster than manually testing 80 versions.
+
+
+
+## Getting Started
+
+Download for [Windows here](https://git-scm.com/download/win).
+Install it and spam *Next* without reading the installation and warning prompts, as always.
+For Linux, `apt-get update && apt-get install --yes git` or whatever.
You likely have it available already.
-Then, somewhere on your machine:
+Then, somewhere on your machine (example for Linux), see also [here](https://www.atlassian.com/git/tutorials/setting-up-a-repository):
```bash
# Create empty directory
@@ -163,7 +162,7 @@ Untracked files:
test.txt
nothing added to commit but untracked files present (use "git add" to track)
-# Do as we are told, like good boys:
+# Rather listen to what we're being told. The dot adds everything:
$ git add .
# There is now a change! The file is ready to be committed, aka "saved" into
# the history.
@@ -199,100 +198,74 @@ your local repository.
You can then sync changes between the two, enabling collaboration (or a bunch of other
advantages if you keep to yourself).
-There are numerous **git GUIs** available.
-They are great at visualizing the commit history (which can get convoluted, if
-you're doing it wrong), but also offer all the regular CLI functionality in GUI form.
-I have nothing to recommend here and am going to distract from this fact using this
-pretty git GUI image from [here](https://unsplash.com/photos/842ofHC6MaI):
+### Graphical Interfaces
+
+There are [numerous git GUIs](https://git-scm.com/download/gui/windows) available.
+For example, they are great at visualizing the commit history (which can get convoluted, especially if you're doing it wrong), but also offer all the regular CLI functionality in GUI form (try [*a dog*](https://stackoverflow.com/a/35075021/11477374) for terminal log visualization).
+[Git for Windows](https://git-scm.com/download/win) comes with a built-in GUI as well, but it's basic:
+
+
-
+Modern, popular IDEs like [VSCode](https://code.visualstudio.com/) have native git support and also offer [git extensions](https://marketplace.visualstudio.com/search?term=git&target=VSCode&category=All%20categories&sortBy=Relevance) which should satisfy all needs.
+They might look like:
-### Git(Lab) and Continuous Delivery
+
+
+## GitLab
GitLab is a platform to host git repositories.
Projects on there can serve as git remotes.
-As mentioned, in this sense, it is like Microsoft's GitHub, the first large website
-to offer such a service (still by far the largest today).
-We use GitLab here because is an *instance* of
-GitLab and therefore freely available to university members.
+As mentioned, in this sense, it is like Microsoft's GitHub, the first large website to offer such a service (still by far the largest today).
+We use GitLab here because is GitLab *instance* and therefore freely available to university members.
+GitLab is a company with their own GitHub competitor at , the source code of which is also open source and therefore be self-hosted (as done in the case of ).
GitLab offers various features for each project.
This includes a Wiki, an issue tracker and pull request management.
-Pull requests (PRs for short; GitLab calls these *Merge Requests*) are requests from
-outside collaborators who have *forked* and subsequently worked on a project.
-Forking projects refers to creating a full copy of the project in the own user space of
-collaborators.
+Pull requests (PRs for short; GitLab calls these *Merge Requests*) are requests from outside collaborators who have *forked* and subsequently worked on a project.
+Forking projects refers to creating a full copy of the project in the own user space of collaborators.
As such, they can then work on it, or do whatever else they want.
-If for example they add a feature, their own copy is now ahead of the original by
-that feature.
-To incorporate the changes back to the original, the original repository's maintainers
-can be *requested* to *pull* in the changes.
+If for example they add a feature, their own copy is now ahead of the original by that feature.
+To incorporate the changes back to the original, the original repository's maintainers can be *requested* to *pull* in the changes.
This way, anyone can collaborate and help, without ever interfering with the main
development in the original.
-**Continuous Delivery** refers to continuously shipping out the finished "product".
-In this case, these are the compiled PDFs.
+### Continuous Delivery (CI)
+
+Continuous Delivery refers to continuously shipping out the finished "product".
+In the case of LaTeX for example, these are the compiled PDFs.
This is done with the help of so-called *Docker containers*.
The advantages are:
-- collaborators no longer rely on their local tool chain, but on a unified, common,
- agreed-upon one.
- It is (usually) guaranteed to work and leads to the same, reproducible, predictable
- results for everyone.
+- collaborators no longer rely on their local tool chain, but on a unified, common, agreed-upon one.
+ It is (usually) guaranteed to work and leads to the same, reproducible, predictable results for everyone.
Docker (also usable locally, not only on the GitLab platform) helps reproduce results:
- across space: results from coworkers in your office or from half-way across the globe.
- You no longer rely on some obscure, specific machine that happens to be the only
- one on which compilation (PDF production) works.
- - across time: if fixed versions are specified, Docker images allow programs, processes
- pipelines etc. from many years ago to run.
+ You no longer rely on some obscure, specific machine that happens to be the only one on which compilation (PDF production) works.
+ - across time: if fixed versions are specified, Docker images allow programs, processes pipelines etc. from many years ago to run.
- If LaTeX documents become very long, full compilation runs can take dozens of minutes.
- This is outsourced and silently done on the remote servers, if Continuous Delivery
- is used.
- As such, for example, every `git push` to the servers triggers a
- [*pipeline*](https://collaborating.tuhh.de/alex/latex-git-cookbook/-/pipelines)
- which compiles the PDF and offers it for download afterwards.
+ This is outsourced and silently done on the remote servers, if Continuous Delivery is used.
+ As such, for example, every `git push` to the servers triggers a [*pipeline*](https://docs.gitlab.com/ee/ci/pipelines/) which compiles the PDF and offers it for download afterwards.
The last part could be called *Continuous Deployment*, albeit a very basic version.
-One concrete workflow to employ this chain is to have a Dockerfile repository on GitHub,
-[like this one](https://github.com/alexpovel/latex-extras-docker).
-GitHub then integrates with [DockerHub](https://hub.docker.com/).
-It allows users to share images.
-As such, there is an image called
-[alexpovel/latex](https://hub.docker.com/repository/docker/alexpovel/latex)
-on DockerHub.
-This *image* was built using the above GitHub *Dockerfile* and can be downloaded and run,
-yielding a live *container*.
-On every `git push` (that is, on every change) in the GitHub repo, this image is rebuilt.
-Given the size of `TeXLive`, this takes about on hour.
-
-Refer to the
-[Dockerfile itself](https://github.com/alexpovel/latex-extras-docker/blob/master/Dockerfile)
-(that Dockerfile is used to compile this very README to PDF via `pandoc`)
-for more details.
-
#### Enable Runner for the project
To build anything, we need someone to build *for* us.
-GitLab calls these build-servers *runners*.
+GitLab calls these build-servers [*runners*](https://docs.gitlab.com/runner/).
Such a runner does not materialize out of thin air.
Luckily, in the case of *collaborating.tuhh.de*, runner `tanis` is available to us.
-Enable it (him? her?) for the project on the GitLab project homepage:
-`Settings -> CI/CD -> Runners -> Enable Shared Runners`.
+Enable it (him? her?) for the project on the GitLab project homepage: `Settings -> CI/CD -> Runners -> Enable Shared Runners`.
Otherwise, the build process will get 'stuck' indefinitely.
#### Add git info to PDF metadata
-After retrieving a built PDF, it might get lost in the nether.
+After retrieving a built PDF, it might get lost in spacetime.
That is, the downloader loses track of what commit it belongs to, or even what release.
This is circumvented by injecting the git SHA into the PDF metadata.
-This allows you to freely hand out PDFs to people, for example for proof-reading or
-to editors of journals.
-You will be able to associate and pinpoint their remarks to a specific, reproducible
-version of the document.
-Note though that such a revision process is (much, much) better done using Pull Requests,
-provided the other party uses git and GitLab.
+This allows you to freely hand out PDFs to people, for example for proof-reading or to editors of journals.
+You will be able to associate and pinpoint their remarks to a specific, reproducible version of the document.
+Note though that such a revision process is (much, much) better done using Pull Requests, provided the other party uses git and GitLab.
To identify versions in git, every object is uniquely identified by its hash
([SHA256](https://stackoverflow.com/a/28792805/11477374)):
@@ -307,111 +280,50 @@ It is convenient to abbreviate the full SHA to a short version:
412ba291
```
-Since a collision of even short hashes is essentially impossible in most use cases,
-we can uniquely identify states of the project by this short SHA.
-This is why commands like `git show 412ba291` work (try it out; the SHA exists in this repository!).
-(As a side note: GitLab picks up on those hashes automatically, as shown in
-[commit `ccedcda0`](https://collaborating.tuhh.de/alex/gitlab-and-latex-ci-presentation/-/commit/ccedcda05d0dd1bb200126aebdaf241d4ecb695d).)
+Since a collision of even short hashes is essentially impossible in most use cases, we can uniquely identify states of the project by this short SHA.
+This is why commands like `git show 412ba291` work.
So if we have this SHA available in the PDF, never again will there be confusion about versions.
The PDF will be be assignable to an exact commit.
It can look like this (in Adobe Reader, evoke file properties with `CTRL + D`):
-
+
Using this approach, it is hidden and will not show up in print.
You can of course also add the info to the document itself, so that it will be printed.
-But how do we get it there?
-
-We have a chicken-and-egg problem:
-if we want to insert the *current* SHA into the *current* source files, we can't.
-While building the *current* PDF, we can only know the SHA of the *previous* commit.
-**But**, fear not, for GitLab has you covered:
-
-During build-time, GitLab provides [*environment variables*](https://docs.gitlab.com/ee/ci/variables/).
-These include things like `CI_COMMIT_SHORT_SHA`, which is exactly what we want.
-Now, we only need to get the contents of that variable into the LaTeX source,
-and finally the compiled PDF.
-
-The LaTeX package `hyperref` can modify PDF metadata.
-In the LaTeX preamble, we can then use, for example,
-
-```latex
-\usepackage[pdfusetitle]{hyperref}% pdfusetitle reads from \author and \title
- \hypersetup{%
- pdfcreator={LaTeX with hyperref (\GitRefName{}, \GitShortSHA{})},
- }
-```
-
-to get metadata like in the PDF above.
-Navigate to the `hyperref` line in the [class file](cookbook.cls) to the see
-current implementation.
-Note that in LaTeX, you likely used `\author{}` and `\title{}`
-somewhere in the preamble to generate a title page.
-`hyperref`'s `pdfusetitle` option will use those values for the PDF metadata.
-Lastly, `pdfcreator` will fill the `Application` field we see above.
-
-However, `\GitRefName{}` and `\GitShortSHA{}}` need to be defined first.
-This happens earlier in the preamble:
-
-```latex
-\directlua{
- dofile("lib/lua/envvar_newcommands.lua")
-}
-```
-
-This runs, with the help of LuaTeX's [Lua](https://www.lua.org/about.html) integration,
-some [Lua code](lib/lua/envvar_newcommands.lua) directly in LaTeX.
-Within Lua, `os.getenv( name)` lets us retrieve environment variables, which are
-then turned into macros/control sequences (`\newcommand`) of a given name using
-`token.set_macro( csname, content)`, see the [LuaTeX reference](http://mirrors.ctan.org/systems/doc/luatex/luatex.pdf)
-on all the included Lua functionality provided by LuaTeX, on top of regular Lua.
#### Add PDF Download Button
-On the top of the project page, we can add *badges*.
+On the top of GitLab project pages, *badges* may be added.
That's how GitLab calls the small, clickable buttons.
-For *real* software developers, these might display code coverage and similar things.
-For, well... *us*, they can be used as a convenient way to download the built PDF.
-It can look like this (center left):
+They can be used as a convenient way for downloading built artifacts, e.g. PDFs.
+It might look like (bottom row):
-
+
A little image (`svg` format) can be generated using [shields.io](https://shields.io/).
-That only needs to be done once, and if you want to reuse the existing ones, here they are:
-
-
-
-
-
-They have been embedded directly into the repository to not have to download them
-each time.
-They could also be embedded via their URL, for example
-.
-To add them to the project, go to:
-`Settings -> General -> Badges`.
-Give it a `Name`, enter the above file path or URL for the `Badge image URL`
-(or do whatever you want here), and finally enter the `Link`.
+That only needs to be done once.
+The result might look like:
+
+
+
+To add them to a project, navigate to: `Settings -> General -> Badges`.
+Give it a `Name`, enter a file path (within the repo) or URL for the `Badge image URL` (or do whatever you want here), and finally enter the `Link`.
This part is a bit tricky, since we need a dynamic URL that adapts to our path.
-For this, GitLab provides variables like `%{project_path}`.
-As such, the URL is (the hyphen in the middle is intentional):
+For this, GitLab provides [variables like `%{project_path}`](https://docs.gitlab.com/ee/user/project/badges.html#placeholders).
+As such, a URL might look like (the hyphen in the middle is intentional):
```bash
-https://collaborating.tuhh.de/%{project_path}/-/jobs/artifacts/%{default_branch}/raw/.pdf?job=build_pdf
+https://collaborating.tuhh.de/%{project_path}/-/jobs/artifacts/%{default_branch}/raw/document.pdf?job=build_pdf
```
-The `project_path` is clear, the `default_branch` is just `master`.
-It visits the job artifacts on `master` and gets the `PDF` with the supplied filename.
-**This filename has to be adjusted accordingly**.
+The `project_path` is just your project with its namespace, like `peter/thesis`, the `default_branch` is usually just `master`.
+It visits the job artifacts on `master` and gets the `PDF` of the supplied filename.
+This filename has to be adjusted accordingly.
Note that the download is **unavailable** while a job is running.
To avoid this, work on a git branch and leave `master` alone.
-Treat the PDF (or whatever it is) on `master` as the current stable version that only changes sometimes,
-not with every commit.
-For example, you can do your continuous business on a `dev` branch and then add a second button,
-
-```bash
-https://collaborating.tuhh.de/%{project_path}/-/jobs/artifacts/dev/raw/.pdf?job=build_pdf
-```
+Treat the PDF (or whatever it is) on `master` as the current stable version that only changes sometimes, not at every commit.
+For example, you can do your continuous business on a `dev` branch and then add a second button.
## Possible issues and pitfalls
diff --git a/images/bitmaps/readme/git-pdf-metadata.jpg b/images/bitmaps/readme/git-pdf-metadata.jpg
new file mode 100644
index 0000000..c8b2779
Binary files /dev/null and b/images/bitmaps/readme/git-pdf-metadata.jpg differ
diff --git a/images/bitmaps/readme/git_sha_in_pdf_metadata.png b/images/bitmaps/readme/git_sha_in_pdf_metadata.png
deleted file mode 100644
index 030698c..0000000
Binary files a/images/bitmaps/readme/git_sha_in_pdf_metadata.png and /dev/null differ
diff --git a/images/bitmaps/readme/pdf_download_button_gitlab.png b/images/bitmaps/readme/pdf_download_button_gitlab.png
deleted file mode 100644
index d8d0336..0000000
Binary files a/images/bitmaps/readme/pdf_download_button_gitlab.png and /dev/null differ
diff --git a/images/bitmaps/readme/yancy-min-842ofHC6MaI-unsplash.jpg b/images/bitmaps/readme/yancy-min-842ofHC6MaI-unsplash.jpg
deleted file mode 100644
index 657a3a8..0000000
Binary files a/images/bitmaps/readme/yancy-min-842ofHC6MaI-unsplash.jpg and /dev/null differ
diff --git a/images/vectors/gitlab/Download-Cookbook-informational.svg b/images/vectors/gitlab/Download-Cookbook-informational.svg
deleted file mode 100644
index 6586d5a..0000000
--- a/images/vectors/gitlab/Download-Cookbook-informational.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/images/vectors/gitlab/Download-PDF-success.svg b/images/vectors/gitlab/Download-PDF-success.svg
deleted file mode 100644
index b9f1595..0000000
--- a/images/vectors/gitlab/Download-PDF-success.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file
diff --git a/images/vectors/gitlab/Download-README-critical.svg b/images/vectors/gitlab/Download-README-critical.svg
deleted file mode 100644
index 3d49b4c..0000000
--- a/images/vectors/gitlab/Download-README-critical.svg
+++ /dev/null
@@ -1 +0,0 @@
-
\ No newline at end of file