Commit 096331c3 authored by Alexander Povel's avatar Alexander Povel
Browse files

Remove architecture doc, distribute info

Put many small READMEs and comments, facilitates exploration and is easier to maintain
parent b37316d2
Pipeline #120885 passed with stages
in 4 minutes and 47 seconds
# 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
......
# 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)
# ======================================================================================
......
# 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
......
#!/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`.
# ======================================================================================
......
# 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.
# 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
......
# **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.
# 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.
# (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.
# 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.
# 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`.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment