112 lines
4.7 KiB
Markdown
112 lines
4.7 KiB
Markdown
# 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}
|
|
```
|