formelsammlung/readme.md

# Formulary
This is supposed to be a compact, searchable collection of the most important stuff I learned during my physics studides,
because it would be a shame if I forget it all!

## Building the PDF
### Dependencies
Any recent **TeX Live** distribution should work. You need:
- `LuaLaTeX` compiler
- several packages from ICAN
- `latexmk` to build it

### With GNU make
1. In the project directory (where this `readme` is), run `make german` or `make english`.
2. Rendered document will be `out/<date>_<formulary>.pdf`

### With Latexmk
1. Choose the language: In `main.tex`, set the language in `\usepackage[english]{babel}` to either `english` or `german`
2. In the `src` directory, run `latexmk -lualatex main.tex`
3. Rendered document will be `out/main.pdf`

### With LuaLatex
1. Choose the language: In `main.tex`, set the language in `\usepackage[english]{babel}` to either `english` or `german`
2. Create the `.aux` directory
3. In the `src` directory, run
    - `lualatex  -output-directory="../.aux"  --interaction=nonstopmode --shell-escape "main.tex"` **3 times**
4. Rendered document will be `.aux/main.pdf`

# LaTeX Guideline
Here is some info to help myself remember why I did things the way I did.

In general, most content should be written with macros, so that the behaviour can be changed later.

## Structure
All translation keys and LaTeX labels should use a structured approach:
`<key type>:<partname>:<section name>:<subsection name>:<...>:<name>`

The `<partname>:...:<lowest section name>` will be defined as `\fqname` (fully qualified name) when using the `\Part`, `\Section`, ... commands.

`<key type>` is:

- formula: `f`
- equation: `eq`
- table: `tab`
- figure: `fig`
- parts, (sub)sections: `sec`

### Files and directories
Separate parts in different source files named `<partname>.tex`.  
If a part should be split up in multiple source files itself, use a
subdirectory named `<partname>` containing `<partname>.tex` and other source files for sections.  
This way, the `fqname` of a section or formula partially matches the path of the source file it is in.

## `formula` environment
The main way to display something is the formula environment:
```tex
\begin{formula}{<key>}
    \desc{English name}{English description}{$q$ is some variable, $s$ \qtyRef{some_quantity}}
    \desc[german]{Deutscher Name}{Deutsche Beschreibung}{$q$ ist eine Variable, $s$ \qtyRef{some_quantity}}
    <content>
\end{formula}
```
Each formula automatically gets a `f:<section names...>:<key>` label.
For the content, several macros are available:
- `\eq{<equation>}` a wrapper for the `align` environment
- `\fig[width]{<path>}`
- `\quantity{<symbol>}{<units>}{<vector, scalar, extensive etc.>}` for physical quantites
- `\constant{<symbol>}{ <values> }` for constants, where `<values>` may contain one or more `\val{value}{unit}` commands.

### References
**Use references where ever possible.**  
In equations, reference or explain every variable. Several referencing commands are available for easy referencing:
- `\fqSecRef{<fqname of section>}` prints the translated title of the section
- `\fqEqRef{<fqname of formula>}` prints the translated title of the formula (first argument of `\desc`)
- `\qtyRef{<key>}` prints the translated name of the quantity
- `\QtyRef{<key>}` prints the symbol and the translated name of the quantity
- `\constRef{<key>}` prints the translated name of the constant
- `\ConstRef{<key>}` prints the symbol and the translated name of the constant
- `\elRef{<symbol>}` prints the symbol of the chemical element
- `\ElRef{<symbol>}` prints the name of the chemical element


## Multilanguage
All text should be defined as a translation (`translations` package, see `util/translation.tex`).
Use `\dt` or `\DT` or the the shorthand language commands `\eng`, `\Eng` etc. to define translations.
These commands also be write the translations to an auxiliary file, which is read after the document begins.
This means (on subsequent compilations) that the translation can be resolved before they are defined.  
Use the `gt` or `GT` macros to retrieve translations.
The english translation of any key must be defined, because it will also be used as fallback.

Lower case macros are relative to the current `fqname`, while upper case macros are absolute.

Never make a macro that would have to be changed if a new language was added, eg dont do
```tex
% 1: key, 2: english version, 3: german version
\newcommand{\mycmd}[3]{
    \dosomestuff{english}{#1}{#2}
    \dosomestuff{german}{#1}{#3}
}

\mycmd{key}{this is english}{das ist deutsch}
```
Instead, do
```tex
% [1]: lang, 2: key, 2: text
\newcommand{\mycmd}[3][english]{
    \dosomestuff{#1}{#2}{#3}
}

\mycmd{key}{this is english}
\mycmd[german]{key}{das ist deutsch}
```