diff --git a/.gitattributes b/.gitattributes index c7428e7..7def9ca 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,3 +1,6 @@ +# This file tells platforms like GitLab how to treat certain files, e.g. +# for syntax highlighting. + # GitLab uses the Rouge Ruby gem; for available languages, see: # https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers diff --git a/.gitignore b/.gitignore index d790c26..8c93365 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,6 @@ +# This file tells git what files *not* to track in its version control. +# Specific files, general suffixes, whole directories etc. can be specified. + # ====================================================================================== # Python (https://raw.githubusercontent.com/github/gitignore/master/Python.gitignore) # ====================================================================================== diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 558a8c9..98f8b7d 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -1,3 +1,8 @@ +# This file configures the GitLab Continuous Integration system, +# and as such has little to do with core git, the version control system. +# See also here: https://docs.gitlab.com/ee/ci/quick_start/#create-a-gitlab-ciyml-file +# It relies heavily on the Makefile, also part of this repository. + # ====================================================================================== # ====================================================================================== # Global defaults, overwritable in each job diff --git a/.latexmkrc b/.latexmkrc index 45143ae..c4a0fb1 100644 --- a/.latexmkrc +++ b/.latexmkrc @@ -1,6 +1,31 @@ #!/bin/env perl -# Shebang is only to get syntax highlighting right across GitLab, GitHub and IDEs. +# This file contains instructions and configurations for the `latexmk` program. +# That program is somewhat like `make`, but tailored to LaTeX. +# LaTeX has a distinct characteristic of regularly requiring *multiple runs* of +# the same program (e.g. `lualatex`) before the build is finished. +# It's a *multi-pass* system. +# In the intermediary runs, latex generates auxiliary files responsible for resolving +# references, links, tables of content etc. + +# `latexmk` knows about these dependencies (otherwise we tell it in this very config +# file, see below), detects these and runs latex (and other, outside programs) +# accordingly. + +# Now, why do we need *both* `latexmk` and `make`? +# Both automate builds. + +# `latexmk` is not powerful enough to cover all use cases. +# `make` is more general and more suitable to be integrated in CI. +# For our latex needs, `make` basically only delegates to `latexmk`. +# We **do not** call e.g. `lualatex` multiple times manually from `make`: +# this logic is left to `latexmk` and `.latexmkrc`. +# However, `make` can also do much more, e.g. cover `pandoc`, clean-up operations etc. +# Therefore, `make` and `latexmkrc` *together* are just super powerful and useful. + + +# The shebang at the top is only to get syntax highlighting right across GitLab, +# GitHub and IDEs. # This file is not meant to be run, but read by `latexmk`. # ====================================================================================== diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 231232b..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,79 +0,0 @@ -# Project Architecture - -Inspired by [this post](https://web.archive.org/web/20210208124935/https://news.ycombinator.com/item?id=26048784). -This file details the project's architecture, including: - -1. the moving parts, -2. certain special directories, -3. certain special files. - -It is pretty overkill and almost presumptuous to have such a file in such a small/simple project. -But it's still a good place to explain a bunch of stuff that can't be explained anywhere else, -even if the "architecture" itself is simple. -The below explanations start from the very basics, assuming very little preexisting knowledge. - -## Moving parts - -The moving parts are mainly the document generation of the main PDF. -Refer to the contents of that PDF itself to get an idea of how that is achieved. - -## Special directories - -- [bib](bib/): Contains bibliographical data: - - Of course, the [bibliography itself](bib/bibliography.bib). - This is auto-generated using [Zotero](https://www.zotero.org/). - Please use a citation management software (any will do), or you will end up hating yourself. - - All sorts of [glossaries](bib/glossaries/), which, thanks to [`bib2gls`](https://ctan.org/pkg/bib2gls), now also come in `bib` format. -- [chapters](chapters/): Your content source `tex` files. - Splitting up files, putting them there and then running `\include` or `\input` on them is a good way of modularisation. -- [data](data/): For example, raw tabular data from experiments. -- [lib](lib/): Library modules, e.g. outsourced latex source code that is better off modularized. - - This directory also contains Lua code. - Embedding Lua for `lualatex` to consume is very cool and we are gladly making use of it. - However, embedding it verbatim into `\directlua` is a bit ugly [and has annoying issues with escaping](https://web.archive.org/web/20210208133949if_/https://www.overleaf.com/learn/latex/Articles/An_Introduction_to_LuaTeX_(Part_2):_Understanding_%5Cdirectlua). - Therefore, we prefer to load external, proper Lua files using `\dofile`. - These files live in [this directory](lib/lua/). -- [pandoc](pandoc/): `pandoc` is a tool almost completely separate from latex. - It is not relevant to the main project and used here only as a cool showcase to convert the Markdown [README](README.md) to PDF (which uses latex in the background). - This directory contains configuration files for `pandoc`. -- [tests](tests/): A Python module to run tests on the produced PDFs. - This can help detect problems as early as possible (that's what CI is all about after all) in a reproducible and reliable way. - Refer to the [README](tests/README.md) there for more info. - -## Special files - -- git: - - [.gitignore](.gitignore): Tells git what files *not* to track in its version control. - - [.gitattributes](.gitattributes): Tells platforms like GitLab to treat certain files in certain, customizable ways. - - [.gitlab-ci.yml](.gitlab-ci.yml): Configures the GitLab Continuous Integration system, and as such has little to do with core git, the version control system. - It relies heavily on the Makefile, see below. -- [Makefile](Makefile): Instructions for the [GNU `make` program](https://www.gnu.org/software/make/). - This program is quite old, very stable, ubiquitous and widely used. - It is a staple in the Linux world. - There are ways to get it to run on Windows, but I haven't tried any. - Use [Windows Subsystem for Linux](https://docs.microsoft.com/en-us/windows/wsl/install-win10) instead and save yourself the headaches. - - `make` runs steps according to the `Makefile` in order to arrive at a target, like a PDF compiled with latex. - It checks all the dependencies automatically and only updates the target if changes in the sources are detected. - - The idea is that this project's PDFs can be compiled by simply calling e.g. `make file.pdf` *both locally and in CI*. - Without make, we would otherwise have very different build steps in local and CI environments. - Additionally, using `make`, the [CI instructions](.gitlab-ci.yml) can be simplified considerably, leading to decoupling. - Moving CI systems then becomes much easier. -- [.latexmkrc](.latexmkrc): Instructions for the `latexmk` program. - This program is somewhat like `make`, but tailored for latex. - Latex has a distinct characteristic of regularly requiring *multiple runs* of the same program (e.g. `lualatex`) before the build is finished. - In the intermediary runs, latex generates auxiliary files responsible for resolving references, links, tables of content etc. - - `latexmk` knows about these dependencies (otherwise we tell it in its `.latexmkrc` config file), detects these and runs latex (and other, outside programs) accordingly. - - Now, why do we need *both* `latexmk` and `make`? - Both automate builds. - - `latexmk` is not powerful enough to cover all use cases. - `make` is more general and more suitable to be integrated in CI. - For our latex needs, `make` basically only delegates to `latexmk`. - We **do not** call e.g. `lualatex` multiple times manually from `make`: this logic is left to `latexmk` and `.latexmkrc`. - However, `make` can also do much more, e.g. cover `pandoc`, clean-up operations etc. - Therefore, `make` and `latexmkrc` *together* are just super powerful and useful. diff --git a/Makefile b/Makefile index 551c9a8..ae51588 100644 --- a/Makefile +++ b/Makefile @@ -1,3 +1,25 @@ +# This file contains instructions for the GNU `make` program: https://www.gnu.org/software/make/ +# +# The program is quite old, very stable, ubiquitous and widely used. +# It is a staple in the Linux world. +# There are ways to get it to run on Windows, but I haven't tried any. +# Use WSL (https://docs.microsoft.com/en-us/windows/wsl/install-win10) instead and +# save yourself the headaches. + +# `make` runs steps according to this very `Makefile` in order to arrive at a target, +# like a PDF compiled with latex. +# It checks all the dependencies automatically and only updates the target if changes +# in the sources are detected. + +# The idea is that this project's PDFs can be compiled by simply calling e.g. +# `make file.pdf` *both locally and in CI*. +# Without make, we would otherwise have very different build steps in local and CI +# environments. +# Additionally, using `make`, the CI instructions (.gitlab-ci.yml) can be simplified +# considerably, leading to decoupling. +# Moving CI systems then becomes much easier. + + # ===================================================================================== # ===================================================================================== # Prerequisites diff --git a/bib/README.md b/bib/README.md new file mode 100644 index 0000000..85b1a67 --- /dev/null +++ b/bib/README.md @@ -0,0 +1,8 @@ +# **Bib**liographical data + +This directory contains: + +1. The [bibliography itself](bibliography.bib). + This is auto-generated using [Zotero](https://www.zotero.org/). + Using citation management software (any will do) will help you out greatly in managing larger literature collections. +1. All sorts of [glossaries](glossaries/), which thanks to [`bib2gls`](https://ctan.org/pkg/bib2gls) now also come in `bib` format. diff --git a/chapters/README.md b/chapters/README.md new file mode 100644 index 0000000..f42f52b --- /dev/null +++ b/chapters/README.md @@ -0,0 +1,5 @@ +# Content files + +This directory contains all the source `tex` files with the document content. +Splitting up files, putting them here and then running `\import` or `\subimport` on them is a good way of modularisation. +It allows to compile only what is needed by commenting out unneeded `\(sub)import` statements, greatly speeding up compilation times. diff --git a/data/README.md b/data/README.md new file mode 100644 index 0000000..d65350e --- /dev/null +++ b/data/README.md @@ -0,0 +1,4 @@ +# (Raw) data + +This directory contains data used inside the main document, e.g. CSV data for `pgfplots`. +You can put all sorts of things here. diff --git a/lib/README.md b/lib/README.md new file mode 100644 index 0000000..2803610 --- /dev/null +++ b/lib/README.md @@ -0,0 +1,10 @@ +# Library code + +This directory might contain, for example: + +- Lua files for usage alongside `lualatex`. + Embedding Lua for `lualatex` to consume is quite powerful and neat, and we are gladly making use of it. + However, embedding Lua verbatim into `\directlua` is a bit ugly [and has annoying issues with escaping](https://web.archive.org/web/20210208133949if_/https://www.overleaf.com/learn/latex/Articles/An_Introduction_to_LuaTeX_(Part_2):_Understanding_%5Cdirectlua). + Therefore, prefer to load external, proper Lua files using `\dofile`. + These files might live in here, if required. +- Outsourced LaTeX source code that is better off modularized, like custom packages. diff --git a/pandoc/README.md b/pandoc/README.md new file mode 100644 index 0000000..399f2d0 --- /dev/null +++ b/pandoc/README.md @@ -0,0 +1,5 @@ +# Pandoc + +`pandoc` is a tool almost completely separate from LaTeX, but goes hand-in-hand with it. +It is not relevant to the main project and used here only as an interesting showcase on how to convert Markdown READMEs to PDF (which uses LaTeX in the background). +This directory contains configuration files for `pandoc`.