| 1 |
\documentclass{ltxdoc} |
| 2 |
|
| 3 |
\EnableCrossrefs |
| 4 |
\CodelineIndex |
| 5 |
\RecordChanges |
| 6 |
|
| 7 |
\usepackage{graphicx} |
| 8 |
\usepackage[highlightmode=immediate]{minted} |
| 9 |
\usepackage{hyperref} |
| 10 |
|
| 11 |
\begin{document} |
| 12 |
|
| 13 |
\title{The \textsf{luatex-type-definitions} package} |
| 14 |
\author{% |
| 15 |
Josef Friedrich\\% |
| 16 |
\url{[email protected]}\\% |
| 17 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API} |
| 18 |
{github.com/Josef-Friedrich/LuaTeX\_Lua-API}% |
| 19 |
} |
| 20 |
\date{v0.2.0 from 2025/07/24} |
| 21 |
|
| 22 |
\maketitle |
| 23 |
|
| 24 |
\newpage |
| 25 |
|
| 26 |
\tableofcontents |
| 27 |
|
| 28 |
\newpage |
| 29 |
|
| 30 |
% \section{Einführung} |
| 31 |
\section{Introduction} |
| 32 |
|
| 33 |
% \href{http://luatex.org}{Lua\TeX} verfügt über eine sehr umfangreiche |
| 34 |
% \href{https://www.lua.org}{Lua} API. --> |
| 35 |
\href{http://luatex.org}{Lua\TeX} has a very large |
| 36 |
\href{https://www.lua.org}{Lua} API. |
| 37 |
% Dieses Projekt versucht, diese API im Texteditor Ihrer Wahl |
| 38 |
% zugänglich zu machen. |
| 39 |
This project tries to make this API accessible in the text editor |
| 40 |
of your choice. |
| 41 |
% Ermöglicht wird dies durch den |
| 42 |
% \href{https://github.com/LuaLS/lua-language-server}{lua-language-server} |
| 43 |
% – einen Server, der das |
| 44 |
% \href{https://en.wikipedia.org/wiki/Language_Server_Protocol}{Language |
| 45 |
% Server Protocol (LSP)} für die Sprache Lua implementiert. |
| 46 |
This is made possible by the |
| 47 |
\href{https://github.com/LuaLS/lua-language-server}{lua-language-server} |
| 48 |
- a server that implements the |
| 49 |
\href{https://en.wikipedia.org/wiki/Language_Server_Protocol}{Language |
| 50 |
Server Protocol (LSP)} for the |Lua| language. |
| 51 |
% Funktionen wie die Syntaxhervorhebung, Code-Vervollständigung und die |
| 52 |
% Markierung von Warnungen und Fehlern sollten daher nicht nur in |
| 53 |
% \href{https://code.visualstudio.com}{Visual Studio Code}, sondern in |
| 54 |
% einer \href{https://langserver.org/#implementations-client}{großen Anzahl an |
| 55 |
% Editoren} möglich |
| 56 |
% sein, die das „LSP“ unterstützen. |
| 57 |
Features such as code completion, syntax highlighting and marking of |
| 58 |
warnings and errors, should therefore not only be possible in |
| 59 |
\href{https://code.visualstudio.com}{Visual Studio Code}, but in a |
| 60 |
\href{https://langserver.org/#implementations-client}{large number of |
| 61 |
editors} that support the |LSP|. |
| 62 |
|
| 63 |
\section{Distribution ...} |
| 64 |
|
| 65 |
\def\TmpImage#1{\includegraphics[width=\linewidth]{resources/images/#1.png}} |
| 66 |
|
| 67 |
\subsection{via CTAN} |
| 68 |
|
| 69 |
\TmpImage{Screenshot_CTAN} |
| 70 |
|
| 71 |
% Die Typ-Definitionen werden auf CTAN als eine einzige Datei |
| 72 |
% veröffentlicht, um das CTAN-Verzeichnis nicht mit vielen einzelnen |
| 73 |
% Lua-Dateien zu überladen. |
| 74 |
The type definitions are published on |
| 75 |
\href{https://www.ctan.org/pkg/luatex-type-definitions}{CTAN} as a |
| 76 |
single file to avoid cluttering the CTAN directory with many individual |
| 77 |
Lua files. |
| 78 |
% Da diese eine Datei knapp 1,5 MB groß ist, muss eine Konfiguration |
| 79 |
% vorgenommen werden, damit der Sprachserver die Datei laden kann. |
| 80 |
Since this one file is just under 1.5 MB in size, a configuration must |
| 81 |
be made so that the language server can load the file. |
| 82 |
% Das folgende Konfigurationsbeispiel legt die Dateigröße für das Laden |
| 83 |
% von Typdefinitionen auf maximal 5000 kB fest. |
| 84 |
The following configuration example sets the preload file size to a |
| 85 |
maximum of 5000 kB. |
| 86 |
|
| 87 |
\begin{verbatim} |
| 88 |
{ |
| 89 |
"Lua.workspace.preloadFileSize": 5000, |
| 90 |
} |
| 91 |
\end{verbatim} |
| 92 |
|
| 93 |
% Es gibt mehrere Möglichkeiten die Typdefinitionen in einem Projekt |
| 94 |
% einzubingen. |
| 95 |
There are several ways to include the type definitions in a project. |
| 96 |
% Am einfachsten ist es, die Datei in den Projektordner zu kopieren. |
| 97 |
The easiest way is to copy the file into the project folder. |
| 98 |
% Oder Sie verwenden die Konfiguration |Lua.workspace.library| |
| 99 |
Or you can use the configuration |Lua.workspace.library|: |
| 100 |
|
| 101 |
\begin{verbatim} |
| 102 |
{ |
| 103 |
"Lua.workspace.library": ["/path/to/luatex-type-definitions.lua"] |
| 104 |
} |
| 105 |
\end{verbatim} |
| 106 |
|
| 107 |
\subsection{via Visual Studio Code Extension} |
| 108 |
|
| 109 |
\TmpImage{Screenshot_VSCode-extension} |
| 110 |
|
| 111 |
\subsection{via Lua Addon Manager (in Visual Studio Code)} |
| 112 |
|
| 113 |
\TmpImage{Screenshot_Lua-Addon-Manager} |
| 114 |
|
| 115 |
\subsection{via LuaCATS git respositories} |
| 116 |
|
| 117 |
\TmpImage{Screenshot_LuaCATS} |
| 118 |
|
| 119 |
\href{https://github.com/LuaCATS}{LuaCATS} is a |
| 120 |
\href{https://github.com}{Github} organisation and stands for \emph{“Lua |
| 121 |
Comment And Type System”}. This organization provides a place for |
| 122 |
community projects to live. These projects are |
| 123 |
\href{https://luals.github.io/wiki/addons}{addons} for popular |
| 124 |
libraries/frameworks. The repositories in this organization are used |
| 125 |
by \href{https://github.com/LuaLS/LLS-Addons}{LLS-Addons}, a repository that is used by the |
| 126 |
\href{https://luals.github.io/wiki/addons/#addon-manager}{addonmanager} |
| 127 |
of the |
| 128 |
\href{https://marketplace.visualstudio.com/items?itemName=sumneko.lua}{ |
| 129 |
VSCodeextension} for the |
| 130 |
\href{https://github.com/LuaLS/lua-language-server}{Lua |
| 131 |
Language Server}. |
| 132 |
|
| 133 |
\subsubsection{All related LuaCATS repositories} |
| 134 |
|
| 135 |
This repositories in LuaCATS are related to this project: |
| 136 |
|
| 137 |
\begin{itemize} |
| 138 |
\item \href{https://github.com/LuaCATS/lmathx}{lmathx} |
| 139 |
\item \href{https://github.com/LuaCATS/lpeg}{lpeg} |
| 140 |
\item \href{https://github.com/LuaCATS/luafilesystem}{luafilesystem} |
| 141 |
\item \href{https://github.com/LuaCATS/luaharfbuzz}{luaharfbuzz} |
| 142 |
\item \href{https://github.com/LuaCATS/luasocket}{luasocket} |
| 143 |
\item \href{https://github.com/LuaCATS/luazip}{luazip} |
| 144 |
\item \href{https://github.com/LuaCATS/lzlib}{lzlib} |
| 145 |
\item \href{https://github.com/LuaCATS/md5}{md5} |
| 146 |
\item \href{https://github.com/LuaCATS/slnunicode}{slnunicode} |
| 147 |
\item \href{https://github.com/LuaCATS/tex-lualatex}{tex-lualatex} |
| 148 |
\item \href{https://github.com/LuaCATS/tex-lualibs}{tex-lualibs} |
| 149 |
\item \href{https://github.com/LuaCATS/tex-luametatex}{tex-luametatex} |
| 150 |
\item \href{https://github.com/LuaCATS/tex-luatex}{tex-luatex} |
| 151 |
\end{itemize} |
| 152 |
|
| 153 |
\subsubsection{Upstream LuaCATS repositories} |
| 154 |
|
| 155 |
% Bei den folgenden Repositories handelt es sich um Upstream-Projekte. |
| 156 |
The following repositories are \emph{upstream} projects. |
| 157 |
% Das bedeutet. |
| 158 |
This means: |
| 159 |
% Die Typdefinitionen werden in einem LuaCATS-Repository entwickelt und |
| 160 |
% von diesem Projekt übernommen. |
| 161 |
The type definitions are developed in a LuaCATS repository and |
| 162 |
\emph{pulled} in by this project. |
| 163 |
|
| 164 |
\def\lArrow{ $\leftarrow$ } |
| 165 |
|
| 166 |
\def\rArrow{ $\rightarrow$ } |
| 167 |
|
| 168 |
\begin{itemize} |
| 169 |
|
| 170 |
\item \href{https://github.com/LuaCATS/lmathx}{LuaCATS: lmathx} \rArrow |
| 171 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luametatex/lmathx.lua}{library/luametatex/lmathx.lua} |
| 172 |
|
| 173 |
\item \href{https://github.com/LuaCATS/lpeg}{LuaCATS: lpeg} \rArrow |
| 174 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/lpeg.lua}{library/luatex/lpeg.lua} |
| 175 |
|
| 176 |
\item \href{https://github.com/LuaCATS/luaharfbuzz}{LuaCATS: luaharfbuzz} \rArrow |
| 177 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/luaharfbuzz.lua}{library/luatex/luaharfbuzz.lua} |
| 178 |
|
| 179 |
\item \href{https://github.com/LuaCATS/luasocket}{LuaCATS: luasocket} \rArrow |
| 180 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/socket.lua}{library/luatex/socket.lua} \rArrow |
| 181 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/mime.lua}{library/luatex/mime.lua} |
| 182 |
|
| 183 |
\item \href{https://github.com/LuaCATS/luazip}{LuaCATS: luazip} \rArrow |
| 184 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zip.lua}{library/luatex/zip.lua} |
| 185 |
|
| 186 |
\item \href{https://github.com/LuaCATS/lzlib}{LuaCATS: lzlib} \rArrow |
| 187 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/zlib.lua}{library/luatex/zlib.lua} |
| 188 |
|
| 189 |
\item \href{https://github.com/LuaCATS/md5}{LuaCATS: md5} \rArrow |
| 190 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/md5.lua}{library/luatex/md5.lua} |
| 191 |
|
| 192 |
\item \href{https://github.com/LuaCATS/slnunicode}{LuaCATS: slnunicode} \rArrow |
| 193 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/blob/main/library/luatex/unicode.lua}{library/luatex/unicode.lua} |
| 194 |
\end{itemize} |
| 195 |
|
| 196 |
\subsubsection{Downstream LuaCATS repositories} |
| 197 |
|
| 198 |
% Bei den folgenden Repositories handelt es sich um Downstream-Projekte. |
| 199 |
The following repositories are \emph{downstream} projects. |
| 200 |
% Das bedeutet. |
| 201 |
This means: |
| 202 |
% Die Typdefinitionen werden in diesem Projekt entwickelt und |
| 203 |
% anschließend in ein LuaCATS-Repository übertragen. |
| 204 |
The type definitions are developed in this project. They are then |
| 205 |
\emph{pushed} into a LuaCATS repository. |
| 206 |
|
| 207 |
\begin{itemize} |
| 208 |
|
| 209 |
\item \href{https://github.com/LuaCATS/tex-lualatex}{LuaCATS: |
| 210 |
tex-lualatex} \lArrow |
| 211 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualatex}{library/lualatex} |
| 212 |
|
| 213 |
\item \href{https://github.com/LuaCATS/tex-luatex}{LuaCATS: tex-luatex} |
| 214 |
\lArrow |
| 215 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luatex}{library/luatex} |
| 216 |
|
| 217 |
\item \href{https://github.com/LuaCATS/tex-lualibs}{LuaCATS: |
| 218 |
tex-lualibs} \lArrow |
| 219 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/lualibs}{library/lualibs} |
| 220 |
|
| 221 |
\item \href{https://github.com/LuaCATS/tex-luametatex}{LuaCATS: |
| 222 |
tex-luametatex} \lArrow |
| 223 |
\href{https://github.com/Josef-Friedrich/LuaTeX_Lua-API/tree/main/library/luametatex}{library/luametatex} |
| 224 |
\end{itemize} |
| 225 |
|
| 226 |
\section{Directory structure of the repository} |
| 227 |
|
| 228 |
In the subfolder |library| are files named after the global libraries |
| 229 |
they document. For example, the |library/tex.lua| file contains the |
| 230 |
documentation for the |tex| library. These \emph{Lua} files don’t contain |
| 231 |
real \emph{Lua} code. They consist only of function bodies and empty |
| 232 |
tables. The main focus is in the docstrings. |
| 233 |
|
| 234 |
The API documentation is written in a |
| 235 |
\href{https://luals.github.io/wiki/annotations}{well documented |
| 236 |
annotation format}. This format is based on the |
| 237 |
\href{https://emmylua.github.io}{EmmyLua} format. Unfortunately, the |
| 238 |
\emph{Lua} community has not yet been able to agree on a standarized |
| 239 |
annotation format. Many \emph{Lua} project are documented in the |
| 240 |
\href{https://github.com/lunarmodules/LDoc}{LDoc} format. However, the |
| 241 |
differences between these formats are marginal. |
| 242 |
|
| 243 |
\subsection{Directory \texttt{library}} |
| 244 |
|
| 245 |
The actual definitions are located in the directory |library|. This |
| 246 |
directory is divided into further subdirectories. In the folder |luatex| |
| 247 |
you will find the definitions that the engine \emph{Lua\TeX} provides. The |
| 248 |
folder |lualibs| documents the extension library of the same name. If |
| 249 |
you use |lualatex|, you may be interested in the folder of the same |
| 250 |
name. |
| 251 |
|
| 252 |
\subsection{Directory \texttt{resources}} |
| 253 |
|
| 254 |
The folder |resources| contains \emph{\TeX} manuals and \emph{HTML} |
| 255 |
online documentation converted into \emph{Lua} docstrings. |
| 256 |
|
| 257 |
\subsection{Directory \texttt{examples}} |
| 258 |
|
| 259 |
% Der Ordner |example| enthält \TeX{}- und \emph{Lua}-Dateien zur |
| 260 |
% Demonstration und zum Testen der dokumentierten Lua-API. |
| 261 |
The |example| folder contains \emph{\TeX{}} and \emph{Lua} files for |
| 262 |
demonstrating and testing the documented \emph{Lua} API. |
| 263 |
|
| 264 |
\pagebreak |
| 265 |
\PrintIndex |
| 266 |
\end{document} |