texlive: document LuaLaTeX font cache (#280080)

lualatex assumes a writeable font cache relative to `$HOME`, for nix this has two implications.
First, the cache might diverge from the nix store if users use LuaLaTeX.
Second, `$HOME` needs to be set to a writable path in derivations.

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/languages-frameworks/texlive.section.md b/doc/languages-frameworks/texlive.section.md
index 8b1ed92a450c1..01b59f6f34a93 100644
--- a/doc/languages-frameworks/texlive.section.md
+++ b/doc/languages-frameworks/texlive.section.md
@@ -208,3 +208,23 @@ EOF
   cp test.pdf $out
 ''
 ```
+
+## LuaLaTeX font cache {#sec-language-texlive-lualatex-font-cache}
+
+The font cache for LuaLaTeX is written to `$HOME`.
+Therefore, it is necessary to set `$HOME` to a writable path, e.g. [before using LuaLaTeX in nix derivations](https://github.com/NixOS/nixpkgs/issues/180639):
+```nix
+runCommandNoCC "lualatex-hello-world" {
+  buildInputs = [ texliveFull ];
+} ''
+  mkdir $out
+  echo '\documentclass{article} \begin{document} Hello world \end{document}' > main.tex
+  env HOME=$(mktemp -d) lualatex  -interaction=nonstopmode -output-format=pdf -output-directory=$out ./main.tex
+''
+```
+
+Additionally, [the cache of a user can diverge from the nix store](https://github.com/NixOS/nixpkgs/issues/278718).
+To resolve font issues that might follow, the cache can be removed by the user:
+```ShellSession
+luaotfload-tool --cache=erase --flush-lookups --force
+```