Debian Codegraph @

texmf-dist/doc/luatex/luatex-type-definitions/luatex-type-definitions-doc.tex

raw
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}