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

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

With Latexmk

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

With LuaLatex

Choose the language: In main.tex, set the language in \usepackage[english]{babel} to either english or german
Create the .aux directory
In the src directory, run
- lualatex -output-directory="../.aux" --interaction=nonstopmode --shell-escape "main.tex" 3 times
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:

\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

% 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

% [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}

4.7 KiB Raw Permalink Blame History