\documentclass{ltxdoc}

\EnableCrossrefs
\CodelineIndex
\RecordChanges

\usepackage{graphicx}
\usepackage[highlightmode=immediate]{minted}
\usepackage{hyperref}

\begin{document}

\title{The \textsf{luatex-type-definitions} package}
\author{%
  Josef Friedrich\\%
  \url{josef@friedrich.rocks}\\%
  \href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API}
       {github.com/Josef-Friedrich/LuaTeX\_Lua-API}%
}
\date{v0.2.0 from 2025/07/24}

\maketitle

\newpage

\tableofcontents

\newpage

% \section{Einführung}
\section{Introduction}

% \href{http://luatex.org}{Lua\TeX} verfügt über eine sehr umfangreiche
% \href{https://www.lua.org}{Lua} API. -->
\href{http://luatex.org}{Lua\TeX} has a very large
\href{https://www.lua.org}{Lua} API.
% Dieses Projekt versucht, diese API im Texteditor Ihrer Wahl
% zugänglich zu machen.
This project tries to make this API accessible in the text editor
of your choice.
% Ermöglicht wird dies durch den
% \href{https://github.com/LuaLS/lua-language-server}{lua-language-server}
% – einen Server, der das
% \href{https://en.wikipedia.org/wiki/Language_Server_Protocol}{Language
% Server Protocol (LSP)} für die Sprache Lua implementiert.
This is made possible by the
\href{https://github.com/LuaLS/lua-language-server}{lua-language-server}
- a server that implements the
\href{https://en.wikipedia.org/wiki/Language_Server_Protocol}{Language
Server Protocol (LSP)} for the |Lua| language.
% Funktionen wie die Syntaxhervorhebung, Code-Vervollständigung und die
% Markierung von Warnungen und Fehlern sollten daher nicht nur in
% \href{https://code.visualstudio.com}{Visual Studio Code}, sondern in
% einer \href{https://langserver.org/#implementations-client}{großen Anzahl an
% Editoren} möglich
% sein, die das „LSP“ unterstützen.
Features such as code completion, syntax highlighting and marking of
warnings and errors, should therefore not only be possible in
\href{https://code.visualstudio.com}{Visual Studio Code}, but in a
\href{https://langserver.org/#implementations-client}{large number of
editors} that support the |LSP|.

\section{Distribution ...}

\def\TmpImage#1{\includegraphics[width=\linewidth]{resources/images/#1.png}}

\subsection{via CTAN}

\TmpImage{Screenshot_CTAN}

% Die Typ-Definitionen werden auf CTAN als eine einzige Datei
% veröffentlicht, um das CTAN-Verzeichnis nicht mit vielen einzelnen
% Lua-Dateien zu überladen.
The type definitions are published on
\href{https://www.ctan.org/pkg/luatex-type-definitions}{CTAN} as a
single file to avoid cluttering the CTAN directory with many individual
Lua files.
% Da diese eine Datei knapp 1,5 MB groß ist, muss eine Konfiguration
% vorgenommen werden, damit der Sprachserver die Datei laden kann.
Since this one file is just under 1.5 MB in size, a configuration must
be made so that the language server can load the file.
% Das folgende Konfigurationsbeispiel legt die Dateigröße für das Laden
% von Typdefinitionen auf maximal 5000 kB fest.
The following configuration example sets the preload file size to a
maximum of 5000 kB.

\begin{verbatim}
{
  "Lua.workspace.preloadFileSize": 5000,
}
\end{verbatim}

% Es gibt mehrere Möglichkeiten die Typdefinitionen in einem Projekt
% einzubingen.
There are several ways to include the type definitions in a project.
% Am einfachsten ist es, die Datei in den Projektordner zu kopieren.
The easiest way is to copy the file into the project folder.
% Oder Sie verwenden die Konfiguration |Lua.workspace.library|
Or you can use the configuration |Lua.workspace.library|:

\begin{verbatim}
{
    "Lua.workspace.library": ["/path/to/luatex-type-definitions.lua"]
}
\end{verbatim}

\subsection{via Visual Studio Code Extension}

\TmpImage{Screenshot_VSCode-extension}

\subsection{via Lua Addon Manager (in Visual Studio Code)}

\TmpImage{Screenshot_Lua-Addon-Manager}

\subsection{via LuaCATS git respositories}

\TmpImage{Screenshot_LuaCATS}

\href{https://github.com/LuaCATS}{LuaCATS} is a
\href{https://github.com}{Github} organisation and stands for \emph{“Lua
Comment And Type System”}. This organization provides a place for
community projects to live. These projects are
\href{https://luals.github.io/wiki/addons}{addons} for popular
libraries/frameworks. The repositories in this organization are used
by \href{https://github.com/LuaLS/LLS-Addons}{LLS-Addons}, a repository that is used by the
\href{https://luals.github.io/wiki/addons/#addon-manager}{addonmanager}
of the
\href{https://marketplace.visualstudio.com/items?itemName=sumneko.lua}{
VSCodeextension} for the
\href{https://github.com/LuaLS/lua-language-server}{Lua
Language Server}.

\subsubsection{All related LuaCATS repositories}

This repositories in LuaCATS are related to this project:

\begin{itemize}
\item \href{https://github.com/LuaCATS/lmathx}{lmathx}
\item \href{https://github.com/LuaCATS/lpeg}{lpeg}
\item \href{https://github.com/LuaCATS/luafilesystem}{luafilesystem}
\item \href{https://github.com/LuaCATS/luaharfbuzz}{luaharfbuzz}
\item \href{https://github.com/LuaCATS/luasocket}{luasocket}
\item \href{https://github.com/LuaCATS/luazip}{luazip}
\item \href{https://github.com/LuaCATS/lzlib}{lzlib}
\item \href{https://github.com/LuaCATS/md5}{md5}
\item \href{https://github.com/LuaCATS/slnunicode}{slnunicode}
\item \href{https://github.com/LuaCATS/tex-lualatex}{tex-lualatex}
\item \href{https://github.com/LuaCATS/tex-lualibs}{tex-lualibs}
\item \href{https://github.com/LuaCATS/tex-luametatex}{tex-luametatex}
\item \href{https://github.com/LuaCATS/tex-luatex}{tex-luatex}
\end{itemize}

\subsubsection{Upstream LuaCATS repositories}

% Bei den folgenden Repositories handelt es sich um Upstream-Projekte.
The following repositories are \emph{upstream} projects.
% Das bedeutet.
This means:
% Die Typdefinitionen werden in einem LuaCATS-Repository entwickelt und
% von diesem Projekt übernommen.
The type definitions are developed in a LuaCATS repository and
\emph{pulled} in by this project.

\def\lArrow{ $\leftarrow$ }

\def\rArrow{ $\rightarrow$ }

\begin{itemize}

\item \href{https://github.com/LuaCATS/lmathx}{LuaCATS: lmathx} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luametatex/lmathx.lua}{library/luametatex/lmathx.lua}

\item \href{https://github.com/LuaCATS/lpeg}{LuaCATS: lpeg} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/lpeg.lua}{library/luatex/lpeg.lua}

\item \href{https://github.com/LuaCATS/luaharfbuzz}{LuaCATS: luaharfbuzz} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/luaharfbuzz.lua}{library/luatex/luaharfbuzz.lua}

\item \href{https://github.com/LuaCATS/luasocket}{LuaCATS: luasocket} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/socket.lua}{library/luatex/socket.lua} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/mime.lua}{library/luatex/mime.lua}

\item \href{https://github.com/LuaCATS/luazip}{LuaCATS: luazip} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zip.lua}{library/luatex/zip.lua}

\item \href{https://github.com/LuaCATS/lzlib}{LuaCATS: lzlib} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zlib.lua}{library/luatex/zlib.lua}

\item \href{https://github.com/LuaCATS/md5}{LuaCATS: md5} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/md5.lua}{library/luatex/md5.lua}

\item \href{https://github.com/LuaCATS/slnunicode}{LuaCATS: slnunicode} \rArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/unicode.lua}{library/luatex/unicode.lua}
\end{itemize}

\subsubsection{Downstream LuaCATS repositories}

% Bei den folgenden Repositories handelt es sich um Downstream-Projekte.
The following repositories are \emph{downstream} projects.
% Das bedeutet.
This means:
% Die Typdefinitionen werden in diesem Projekt entwickelt und
% anschließend in ein LuaCATS-Repository übertragen.
The type definitions are developed in this project. They are then
\emph{pushed} into a LuaCATS repository.

\begin{itemize}

\item \href{https://github.com/LuaCATS/tex-lualatex}{LuaCATS:
tex-lualatex} \lArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualatex}{library/lualatex}

\item \href{https://github.com/LuaCATS/tex-luatex}{LuaCATS: tex-luatex}
\lArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luatex}{library/luatex}

\item \href{https://github.com/LuaCATS/tex-lualibs}{LuaCATS:
tex-lualibs} \lArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualibs}{library/lualibs}

\item \href{https://github.com/LuaCATS/tex-luametatex}{LuaCATS:
tex-luametatex} \lArrow
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luametatex}{library/luametatex}
\end{itemize}

\section{Directory structure of the repository}

In the subfolder |library| are files named after the global libraries
they document. For example, the |library/tex.lua| file contains the
documentation for the |tex| library. These \emph{Lua} files don’t contain
real \emph{Lua} code. They consist only of function bodies and empty
tables. The main focus is in the docstrings.

The API documentation is written in a
\href{https://luals.github.io/wiki/annotations}{well documented
annotation format}. This format is based on the
\href{https://emmylua.github.io}{EmmyLua} format. Unfortunately, the
\emph{Lua} community has not yet been able to agree on a standarized
annotation format. Many \emph{Lua} project are documented in the
\href{https://github.com/lunarmodules/LDoc}{LDoc} format. However, the
differences between these formats are marginal.

\subsection{Directory \texttt{library}}

The actual definitions are located in the directory |library|. This
directory is divided into further subdirectories. In the folder |luatex|
you will find the definitions that the engine \emph{Lua\TeX} provides. The
folder |lualibs| documents the extension library of the same name. If
you use |lualatex|, you may be interested in the folder of the same
name.

\subsection{Directory \texttt{resources}}

The folder |resources| contains \emph{\TeX} manuals and \emph{HTML}
online documentation converted into \emph{Lua} docstrings.

\subsection{Directory \texttt{examples}}

% Der Ordner |example| enthält \TeX{}- und \emph{Lua}-Dateien zur
% Demonstration und zum Testen der dokumentierten Lua-API.
The |example| folder contains \emph{\TeX{}} and \emph{Lua} files for
demonstrating and testing the documented \emph{Lua} API.

\pagebreak
\PrintIndex
\end{document}