summaryrefslogtreecommitdiff
path: root/macros/luatex/generic/luakeys/luakeys-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/luatex/generic/luakeys/luakeys-doc.tex')
-rw-r--r--macros/luatex/generic/luakeys/luakeys-doc.tex726
1 files changed, 524 insertions, 202 deletions
diff --git a/macros/luatex/generic/luakeys/luakeys-doc.tex b/macros/luatex/generic/luakeys/luakeys-doc.tex
index bc9a55f632..dd6fcc0973 100644
--- a/macros/luatex/generic/luakeys/luakeys-doc.tex
+++ b/macros/luatex/generic/luakeys/luakeys-doc.tex
@@ -1,12 +1,12 @@
\documentclass{ltxdoc}
-\usepackage[hidelinks]{hyperref}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\usepackage{mdframed}
\usepackage{minted}
+\usepackage{luakeys}
\usepackage{luakeys-debug}
\usepackage{multicol}
\usepackage{luacode}
@@ -22,19 +22,30 @@
\def\lua#1{\mintinline{lua}|#1|}
\def\latex#1{\mintinline{latex}|#1|}
-\NewDocumentCommand { \InputLatexExample } { O{} m } {
+\NewDocumentCommand { \InputLatex } { O{} m } {
\begin{mdframed}
\inputminted[linenos=false,#1]{latex}{examples/#2}
\end{mdframed}
}
-\NewDocumentCommand { \InputLuaExample } { O{} m } {
+\NewDocumentCommand { \InputLua } { O{} m } {
\begin{mdframed}
\inputminted[linenos=false,#1]{lua}{examples/#2}
\end{mdframed}
}
\catcode`_=12
+\def\DefaultOpt#1{%
+ \texttt{\directlua{
+ tex.print(luakeys.print_default('opts', '#1'))
+ }}%
+}
+
+\def\DefaultOptDescription#1{
+\noindent
+The default value of the option “\texttt{#1}” is:
+\DefaultOpt{#1}.
+}
\begin{document}
@@ -44,15 +55,16 @@
\author{%
Josef Friedrich\\%
\url{josef@friedrich.rocks}\\%
- \href{https://github.com/Josef-Friedrich/luakeys}{github.com/Josef-Friedrich/luakeys}%
+ \href{https://github.com/Josef-Friedrich/luakeys}
+ {github.com/Josef-Friedrich/luakeys}%
}
-\date{v0.6 from 2022/06/09}
+\date{0.7.0 from 2022/07/06}
\maketitle
\vfill
-\InputLuaExample[firstline=4,lastline=7]{first-page.lua}
+\InputLua[firstline=4,lastline=7]{first-page.lua}
\noindent
Result:
@@ -83,6 +95,7 @@ Result:
\newpage
+% \section{Einführung}
\section{Introduction}
\noindent
@@ -112,20 +125,62 @@ Since |luakeys| uses
\href{http://www.inf.puc-rio.br/~roberto/lpeg/}{LPeg}, the parsing
mechanism should be pretty robust.
+% Der Artikel TUGboat
+% \href{http://www.tug.org/tugboat/tb30-1/tb94wright-keyval.pdf}
+% {“Implementing key–value input: An introduction” (Volume 30 (2009), No.
+% 1)} von \emph{Joseph Wright} und \emph{Christian Feuersänger} gibt einen
+% einen guten Überblick über die verfügbaren Key-Value-Pakete.
The TUGboat article
\href{http://www.tug.org/tugboat/tb30-1/tb94wright-keyval.pdf}
-{“Implementing key–value input: An introduction” (Volume 30 (2009), No. 1)}
-by \emph{Joseph Wright} and \emph{Christian Feuersänger} gives a good
-overview of the available key-value packages.
-
+{“Implementing key–value input: An introduction” (Volume 30 (2009), No.
+1)} by \emph{Joseph Wright} and \emph{Christian Feuersänger} gives a
+good overview of the available key-value packages.
+
+% Dieses Paket wäre ohne den Artikel
+% \href{https://tug.org/TUGboat/tb40-2/tb125menke-lpeg.pdf}
+% {"Parsing complex data formats in LuaTEX with LPEG" (Volume 40 (2019),
+% No. 2)} nicht möglich gewesen.
This package would not be possible without the article
\href{https://tug.org/TUGboat/tb40-2/tb125menke-lpeg.pdf}
-{“Parsing complex data formats in LuaTEX with LPEG” (Volume 40 (2019), No. 2)}.
+{“Parsing complex data formats in LuaTEX with LPEG” (Volume 40 (2019),
+No. 2)}.
+
+\subsection{Pros of \texttt{luakeys}}
+
+\begin{itemize}
+% \item Schlüssel-Wert-Paare können unabhängig vom Makro-Paket (latex or
+% context) analysiert werden.
+\item Key-value pairs can be parsed independently of the macro
+collection (\LaTeX{} or Con\TeX{}t).
+
+% \item Sogar in Plain LuaTex können Schlüssel analysiert werden
+\item Even in plain Lua\TeX{} keys can be parsed.
+
+% \item |luakeys| kann mit ineinander verschachtelten listen an
+% Schlüssel-Wert-Paaren umgehen, d. h. es kann mit einer rekursiven
+% Datenstruktur an Schlüssel umgehen.
+\item |luakeys| can handle nested lists of key-value pairs, i.e. it can
+handle a recursive data structure of keys.
+
+% \item Schlüssel müssen nicht, aber können definiert werden.
+\item Keys do not have to be defined, but can they can be defined.
+\end{itemize}
+
+\subsection{Cons of \texttt{luakeys}}
+
+\begin{itemize}
+% \item Das Packet funktioniert nur in der Verbindung mit Lua\TeX.
+\item The package works only in combination with Lua\TeX.
+
+% \item Du musst zwei Sprachen beherrschen: \TeX{} und Lua.
+\item You need to know two languages: \TeX{} and Lua.
+\end{itemize}
%-----------------------------------------------------------------------
%
%-----------------------------------------------------------------------
+% \section{Wie das Paket geladen wird}
\section{How the package is loaded}
%%
@@ -142,7 +197,7 @@ The core functionality of this package is realized in Lua.
So you can use |luakeys| even without using the wrapper files
|luakeys.sty| and |luakeys.tex|.
-\InputLatexExample{loading/lua.tex}
+\InputLatex{loading/lua.tex}
%%
%
@@ -155,8 +210,8 @@ So you can use |luakeys| even without using the wrapper files
For example, the MiK\TeX{} package manager downloads packages only when
needed.
%
-% Es wurde berichtet, dass dieser automatische Download nur mit Hilfe der
-% Hüll-Dateien funktioniert.
+% Es wurde berichtet, dass dieser automatische Download nur mit Hilfe
+% der Hüll-Dateien funktioniert.
It has been reported that this automatic download only works with this
wrapper files.
%
@@ -164,7 +219,7 @@ wrapper files.
% “\latex{\usepackage{luakeys}} ”Ausschau.
Probably MiK\TeX{} is searching for an occurrence of the \LaTeX{} macro
“\latex{\usepackage{luakeys}}”.
-
+%
% Die mitgelieferte Lua\LaTeX{}-Datei ist recht klein:
The supplied Lua\LaTeX{} file is quite small:
@@ -175,38 +230,62 @@ The supplied Lua\LaTeX{} file is quite small:
\end{minted}
\noindent
+% Es lädt das Lua-Modul in die globale Variable \texttt{luakeys}.
It loads the Lua module into the global variable \texttt{luakeys}.
-\InputLatexExample{loading/latex.tex}
+\InputLatex{loading/tex-latex.tex}
%%
%
%%
+% \subsection{Verwendung des Plain-Lua\TeX{}-Hüllpakets
+% \texttt{luakeys.tex}}
\subsection{Using the plain Lua\TeX{} wrapper \texttt{luakeys.tex}}
-Even smaller is the file \texttt{luakeys.tex}. It consists of only one
-line:
+% Noch kleiner ist die Datei \texttt{luakeys.tex}.
+Even smaller is the file \texttt{luakeys.tex}.
+%
+% Sie besteht aus nur einer Zeile:
+It consists of only one line:
\begin{minted}{latex}
\directlua{luakeys = require('luakeys')}
\end{minted}
\noindent
+% Es macht dasselbe wie das Lua\LaTeX{}-Hüllpacket und lädt das
+% Lua-Modul \texttt{luakeys.lua} in die globale Variable
+% \texttt{luakeys}.
It does the same as the Lua\LaTeX{} wrapper and loads the Lua module
\texttt{luakeys.lua} into the global variable \texttt{luakeys}.
-\InputLatexExample{loading/tex.tex}
+\InputLatex{loading/tex-plain.tex}
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Lua interface / API}
-To learn more about the individual functions (local functions), please
+% Das Lua-Modul exportiert diese Funktionen und Tabellen:
+The Lua module exports this functions and tables:
+
+\InputLua[firstline=3,lastline=13]{export.lua}
+
+% Diese Dokumentation stellt nur die öffentlichen Funktionen und
+% Tabellen vor.
+This documentation presents only the public functions and tables.
+%
+% Um mehr über die privaten, nicht exportierten Funktionen zu erfahren,
+% lesen Sie bitte die
+% \href{https://josef-friedrich.github.io/luakeys/}{Quellcode
+% Dokumentation}, die mit
+% \href{http://stevedonovan.github.io/ldoc/}{LDoc} erstellt wurde.
+To learn more about the private, not exported functions, please
read the \href{https://josef-friedrich.github.io/luakeys/}{source code
documentation}, which was created with
-\href{http://stevedonovan.github.io/ldoc/}{LDoc}. The Lua module exports
-this functions and tables:
-
-\InputLuaExample[firstline=3,lastline=12]{export.lua}
+\href{http://stevedonovan.github.io/ldoc/}{LDoc}.
\subsection{Lua indentifier names}
@@ -219,7 +298,8 @@ hopefully unambiguous and familiar to external readers.
\begin{tabular}{lll}
Abbreviation & spelled out & Example \\\hline
\lua{kv_string} & Key-value string & \lua{'key=value'} \\
-\lua{opts} & Options (for the parse function) & \lua{ { no_error = false } } \\
+\lua{opts} & Options (for the parse function) &
+\lua{ { no_error = false } } \\
\lua{defs} & Definitions \\
\lua{def} & Definition \\
\lua{attr} & Attributes (of a definition) \\
@@ -233,7 +313,8 @@ These unabbreviated variable names are commonly used.
\begin{tabular}{ll}
\lua{result} &
-% Das Endergebnis aller einzelnen Übersetzungs- und Normalisierungsschritte
+% Das Endergebnis aller einzelnen Übersetzungs- und
+% Normalisierungsschritte
The final result of all individual parsing and normalization steps. \\
\lua{unknown} &
@@ -250,54 +331,41 @@ The raw result of the Lpeg grammar parser. \\
%
%%
-\subsection{Function \texttt{parse(kv_string, opts): result, unknown, raw}}
+\subsection{Function “\texttt{parse(kv_string, opts): result, unknown,
+raw}”}
\label{parse}
% Die Function parse ist die wichtigste Funktion des Pakets.
The function \lua{parse(kv_string, opts)} is the most important function
of the package.
+%
+%
% Sie konvertiert eine Schlüssel-Wert-Zeichenkette in eine Lua Tabelle.
It converts a key-value string into a Lua table.
-\begin{minted}{latex}
-\newcommand{\mykeyvalcmd}[2][]{
- \directlua{
- result = luakeys.parse('#1')
- luakeys.debug(result)
- }
- #2
-}
-\mykeyvalcmd[one=1]{test}
-\end{minted}
+\InputLatex{functions/parse/tex-latex.tex}
\noindent
In plain \TeX:
-\begin{minted}{latex}
-\def\mykeyvalcommand#1{
- \directlua{
- result = luakeys.parse('#1')
- luakeys.debug(result)
- }
-}
-\mykeyvalcmd{one=1}
-\end{minted}
+\InputLatex{functions/parse/tex-plain.tex}
\subsection{Options to configure the \texttt{parse} function}
\noindent
The \lua{parse} function can be called with an options table. This
-options are supported:
+options are supported: \catcode`_=12
+\directlua{luakeys.print_names('opts')}
-\InputLuaExample[firstline=5,lastline=69]{opts/all-opts.lua}
+\InputLua[firstline=5,lastline=69]{opts/all-opts.lua}
\noindent
The options can also be set globally using the exported table
|opts|:
-\InputLuaExample[firstline=4,lastline=4]{opts/exported-default-opts.lua}
+\InputLua[firstline=4,lastline=4]{opts/exported-default-opts.lua}
-\InputLuaExample[firstline=10,lastline=11]{opts/exported-default-opts.lua}
+\InputLua[firstline=10,lastline=11]{opts/exported-default-opts.lua}
%%
%
@@ -305,45 +373,49 @@ The options can also be set globally using the exported table
\subsubsection{Option “\texttt{convert_dimensions}”}
+% Wenn Sie die Option \lua{convert_dimensions} auf \lua{true} setzen,
+% erkennt |luakeys| die \TeX{}-Dimensionen und konvertiert sie mit Hilfe
+% der die Funktion \lua{tex.sp(dim)} in scaled points.
If you set the option \lua{convert_dimensions} to \lua{true}, |luakeys|
detects the \TeX{} dimensions and converts them into scaled points using
the function \lua{tex.sp(dim)}.
-\InputLuaExample[firstline=4,lastline=7]{opts/convert-dimensions.lua}
+\InputLua[firstline=4,lastline=7]{opts/convert-dimensions/true.lua}
\noindent
+% Standardmäßig werden die Dimensionen nicht in skalierte Punkte
+% umgewandelt.
By default the dimensions are not converted into scaled points.
-\InputLuaExample[firstline=13,lastline=18]{opts/convert-dimensions.lua}
+\InputLua[firstline=4,lastline=9]{opts/convert-dimensions/false.lua}
\noindent
-If you want to convert a scale point into a unit string you can use the module
-\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua}{lualibs-util-dim.lua}.
+% Wenn Sie eine skalierte Punktzahl in einen Dimensionszeichenketten
+% umwandeln möchten, können Sie das Modul
+If you want to convert a scaled points number into a dimension string
+you can use the module
+\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua}
+{lualibs-util-dim.lua}.
\begin{minted}{lua}
require('lualibs')
tex.print(number.todimen(tex.sp('1cm'), 'cm', '%0.0F%s'))
\end{minted}
+\DefaultOptDescription{convert_dimensions}
+
%%
%
%%
\subsubsection{Option “\texttt{debug}”}
-If the option “debug” is set to ture, the result table is printed to the
-console.
+% Wenn die Option \lua{debug} auf true gesetzt ist, wird die
+% Ergebnistabelle in der Konsole ausgegeben.
+If the option \lua{debug} is set to ture, the result table is printed to
+the console.
-\begin{minted}{latex}
-\documentclass{article}
-\usepackage{luakeys}
-\begin{document}
-\directlua{
- luakeys.parse('one,two,three', { debug = true })
-}
-debug
-\end{document}
-\end{minted}
+\InputLatex{opts/debug-latex.tex}
\begin{verbatim}
This is LuaHBTeX, Version 1.15.0 (TeX Live 2022)
@@ -361,6 +433,8 @@ local/texlive/2022/texmf-var/fonts/map/pdftex/updmap/pdftex.map}] (./debug.aux)
Transcript written on debug.log.
\end{verbatim}
+\DefaultOptDescription{debug}
+
%%
%
%%
@@ -375,13 +449,15 @@ The option \lua{default} can be used to specify which value naked keys
(keys without a value) get. This option has no influence on keys with
values.
-\InputLuaExample[firstline=4,lastline=5]{opts/default.lua}
+\InputLua[firstline=4,lastline=5]{opts/default.lua}
\noindent
% Standardmäßig erhalten nackte Schlüssel den Wert \lua{true}.
By default, naked keys get the value \lua{true}.
-\InputLuaExample[firstline=11,lastline=12]{opts/default.lua}
+\InputLua[firstline=11,lastline=12]{opts/default.lua}
+
+\DefaultOptDescription{default}
%%
%
@@ -402,7 +478,9 @@ The result table is merged into the defaults table.
Values in the defaults table are
overwritten by values in the result table.
-\InputLuaExample[firstline=4,lastline=7]{opts/defaults.lua}
+\InputLua[firstline=4,lastline=7]{opts/defaults.lua}
+
+\DefaultOptDescription{defaults}
%%
%
@@ -421,13 +499,15 @@ If you use the \lua{defs} option, you don't need to call the
% Anstatt
Instead of ...
-\InputLuaExample[firstline=4,lastline=5]{opts/defs.lua}
+\InputLua[firstline=4,lastline=5]{opts/defs.lua}
\noindent
% können wir schreiben ..
we can write ...
-\InputLuaExample[firstline=11,lastline=13]{opts/defs.lua}
+\InputLua[firstline=11,lastline=13]{opts/defs.lua}
+
+\DefaultOptDescription{defs}
%%
%
@@ -438,17 +518,19 @@ we can write ...
\begin{description}
\item[lower] \strut
-\InputLuaExample[firstline=4,lastline=5]{opts/format-keys.lua}
+\InputLua[firstline=4,lastline=5]{opts/format-keys.lua}
\item[snake] \strut
-\InputLuaExample[firstline=11,lastline=12]{opts/format-keys.lua}
+\InputLua[firstline=11,lastline=12]{opts/format-keys.lua}
\item[upper] \strut
-\InputLuaExample[firstline=18,lastline=19]{opts/format-keys.lua}
+\InputLua[firstline=18,lastline=19]{opts/format-keys.lua}
\end{description}
+\DefaultOptDescription{format_keys}
+
%%
%
%%
@@ -463,8 +545,8 @@ processing of the \lua{parse} function.
% Die Funktionen sind in der Verarbeitungsreihenfolge aufgelistet.
The functions are listed in processing order.
%
-% \lua{*_before_opts} bedeutet, dass die Hooks nach der LPeg Syntaxanalyse
-% und vor dem Anwenden der Optionen ausgeführt
+% \lua{*_before_opts} bedeutet, dass die Hooks nach der LPeg
+% Syntaxanalyse und vor dem Anwenden der Optionen ausgeführt
\lua{*_before_opts} means that the hooks are executed after the LPeg
syntax analysis and before the options are applied.
%
@@ -504,7 +586,7 @@ definitions.
The \lua{kv_string} hook is called as the first of the hook functions
before the LPeg syntax parser is executed.
-\InputLuaExample[firstline=4,lastline=11]{hooks/kv-string.lua}
+\InputLua[firstline=4,lastline=11]{hooks/kv-string.lua}
\paragraph{\texttt{keys_*}}
@@ -515,12 +597,12 @@ result table.
% Die Hook-Funktion muss zwei Werte zurückgeben: \lua{key, value}
The hook function must return two values: \lua{key, value}.
%
-% Das folgende Beispiel gibt \lua{key} und \lua{value} unverändert zurück,
-% sodass die Ergebnistabelle nicht verändert wird.
+% Das folgende Beispiel gibt \lua{key} und \lua{value} unverändert
+% zurück, sodass die Ergebnistabelle nicht verändert wird.
The following example returns \lua{key} and \lua{value} unchanged, so
the result table is not changed.
-\InputLuaExample[firstline=4,lastline=11]{hooks/keys-unchanged.lua}
+\InputLua[firstline=4,lastline=11]{hooks/keys-unchanged.lua}
\noindent
% Das nächste Beispiel demonstriert den dritten Parameter \lua{depth}
@@ -528,7 +610,7 @@ the result table is not changed.
The next example demonstrates the third parameter \lua{depth} of the
hook function.
-\InputLuaExample[firstline=4,lastline=16]{hooks/keys-depth.lua}
+\InputLua[firstline=4,lastline=16]{hooks/keys-depth.lua}
\paragraph{\texttt{result_*}}
@@ -549,12 +631,14 @@ as a parameter.
With the help of the option \lua{naked_as_value}, naked keys are not
given a default value, but are stored as values in a Lua table.
-\InputLuaExample[firstline=4,lastline=5]{opts/naked-as-value.lua}
+\InputLua[firstline=4,lastline=5]{opts/naked-as-value.lua}
\noindent
If we set the option \lua{naked_as_value} to \lua{true}:
-\InputLuaExample[firstline=11,lastline=14]{opts/naked-as-value.lua}
+\InputLua[firstline=11,lastline=14]{opts/naked-as-value.lua}
+
+\DefaultOptDescription{naked_as_value}
%%
%
@@ -568,12 +652,14 @@ By default the parse function throws an error if there are unknown keys.
% Mit Hilfe der Option \lua{no_error} kann dies unterbunden werden.
This can be prevented with the help of the \lua{no_error} option.
-\InputLuaExample[firstline=5,lastline=6]{opts/no-error.lua}
+\InputLua[firstline=5,lastline=6]{opts/no-error.lua}
\noindent
If we set the option \lua{no_error} to \lua{true}:
-\InputLuaExample[firstline=9,lastline=10]{opts/no-error.lua}
+\InputLua[firstline=9,lastline=10]{opts/no-error.lua}
+
+\DefaultOptDescription{no_error}
%%
%
@@ -587,15 +673,17 @@ If we set the option \lua{no_error} to \lua{true}:
With the help of the option \lua{unpack}, all tables that consist of
only one a single naked key or a single standalone value are unpacked.
-\InputLuaExample[firstline=4,lastline=5]{opts/unpack.lua}
+\InputLua[firstline=4,lastline=5]{opts/unpack.lua}
+
+\InputLua[firstline=11,lastline=12]{opts/unpack.lua}
-\InputLuaExample[firstline=11,lastline=12]{opts/unpack.lua}
+\DefaultOptDescription{unpack}
%%
%
%%
-\subsection{Function \texttt{define(defs, opts): parse}}
+\subsection{Function “\texttt{define(defs, opts): parse}”}
\label{define}
The \lua{define} function returns a \lua{parse} function (see
@@ -609,13 +697,13 @@ key-value pair is then stored under this key.
\item by the “name” attribute.
\end{enumerate}
-\InputLuaExample[firstline=4,lastline=16]{functions/define.lua}
+\InputLua[firstline=4,lastline=16]{functions/define.lua}
\noindent
For nested definitions, only the last two ways of specifying the key
names can be used.
-\InputLuaExample[firstline=26,lastline=33]{functions/define.lua}
+\InputLua[firstline=26,lastline=33]{functions/define.lua}
%-----------------------------------------------------------------------
%
@@ -636,12 +724,16 @@ The name \emph{“attribute”} for an option, a key, a property ... (to
list just a few naming possibilities) to define keys, was deliberately
chosen to distinguish them from the options of the \lua{parse} function.
%
+% Diese Attribute sind erlaubt.
+These attributes are allowed:
+\directlua{luakeys.print_names('attrs')}.
+%
% Das folgende Codebeispiel listet alle Attribute auf, die verwendet
% werden können, um Schlüssel-Wert-Paare zu definieren.
The code example below lists all the attributes that can be used to
define key-value pairs.
-\InputLuaExample[firstline=5,lastline=41]{defs/all-attrs.lua}
+\InputLua[firstline=5,lastline=46]{defs/all-attrs.lua}
%%
%
@@ -653,12 +745,12 @@ With the help of the \lua{alias} attribute, other key names can be used.
The value is always stored under the original key name. A single alias
name can be specified by a string ...
-\InputLuaExample[firstline=4,lastline=7]{defs/attrs/alias.lua}
+\InputLua[firstline=4,lastline=7]{defs/attrs/alias.lua}
\noindent
multiple aliases by a list of strings.
-\InputLuaExample[firstline=13,lastline=16]{defs/attrs/alias.lua}
+\InputLua[firstline=13,lastline=16]{defs/attrs/alias.lua}
%%
%
@@ -669,7 +761,7 @@ multiple aliases by a list of strings.
% Die Option \lua{default} wird nur bei nackten Schlüsseln verwendet.
The \lua{default} attribute is used only for naked keys.
-\InputLuaExample[firstline=4,lastline=5]{defs/attrs/always-present.lua}
+\InputLua[firstline=4,lastline=5]{defs/attrs/always-present.lua}
\noindent
% Wird die Option \lua{always_present} auf wahr gesetzt, wird der
@@ -678,7 +770,7 @@ If the attribute \lua{always_present} is set to true, the key is always
included in the result. If no default value is definied, true is taken
as the value.
-\InputLuaExample[firstline=11,lastline=12]{defs/attrs/always-present.lua}
+\InputLua[firstline=11,lastline=12]{defs/attrs/always-present.lua}
%%
%
@@ -690,14 +782,14 @@ as the value.
Some key values should be selected from a restricted set of choices.
These can be handled by passing an array table containing choices.
-\InputLuaExample[firstline=4,lastline=5]{defs/attrs/choices.lua}
+\InputLua[firstline=4,lastline=5]{defs/attrs/choices.lua}
\noindent
When the key-value pair is parsed, values will be checked, and an error
message will be displayed if the value was not one of the acceptable
choices:
-\InputLuaExample[firstline=13,lastline=15]{defs/attrs/choices.lua}
+\InputLua[firstline=13,lastline=15]{defs/attrs/choices.lua}
%%
%
@@ -727,8 +819,8 @@ A type conversion can fail with the three data types
% Dann wird eine Fehlermeldung ausgegeben.
Then an error message is displayed.
-\InputLuaExample[firstline=4,lastline=8]{defs/attrs/data-type.lua}
-\InputLuaExample[firstline=11,lastline=15]{defs/attrs/data-type.lua}
+\InputLua[firstline=4,lastline=8]{defs/attrs/data-type.lua}
+\InputLua[firstline=11,lastline=15]{defs/attrs/data-type.lua}
%%
%
@@ -746,7 +838,7 @@ key individually.
With the global \lua{default} attribute (\ref{option-default}) a default
value can be specified for all naked keys.
-\InputLuaExample[firstline=4,lastline=9]{defs/attrs/default.lua}
+\InputLua[firstline=4,lastline=9]{defs/attrs/default.lua}
%%
%
@@ -766,14 +858,15 @@ Only one key from this group is allowed.
% Wert verwendet werden.
Any value can be used as a name for this exclusive group.
-\InputLuaExample[firstline=4,lastline=9]{defs/attrs/exclusive-group.lua}
+\InputLua[firstline=4,lastline=9]{defs/attrs/exclusive-group.lua}
+\noindent
% Werden mehrer Schlüssel der Gruppe angegeben, so wird eine
% Fehlermeldung geworfen.
If more than one key of the group is specified, an error message is
thrown.
-\InputLuaExample[firstline=21,lastline=23]{defs/attrs/exclusive-group.lua}
+\InputLua[firstline=21,lastline=23]{defs/attrs/exclusive-group.lua}
%%
%
@@ -809,13 +902,13 @@ opposite key pair.
If the key \lua{show} is parsed by the \lua{parse} function, then the
target key \lua{visibility} receives the value \lua{true}.
-\InputLuaExample[firstline=4,lastline=7]{defs/attrs/opposite-keys.lua}
+\InputLua[firstline=4,lastline=7]{defs/attrs/opposite-keys.lua}
% Wird der Schlüssel \lua{hide} gelesen, dann \lua{falsch}.
\noindent
If the key \lua{hide} is parsed, then \lua{false}.
-\InputLuaExample[firstline=13,lastline=13]{defs/attrs/opposite-keys.lua}
+\InputLua[firstline=13,lastline=13]{defs/attrs/opposite-keys.lua}
%%
%
@@ -844,21 +937,31 @@ parse('key=value')
\subsubsection{Attribute “\texttt{match}”}
-% Der Wert des Schlüssel wird der Lua Funktion übergeben
-The value of the key is passed to the Lua function
-\lua{string.match(value, match)} ((\url{http://www.lua.org/manual/5.3/manual.html#pdf-string.match})).
+% Der Wert des Schlüssel wird zuerst der Lua Funktion
+% \lua{string.match(value, match)} übergeben, bevor er dem Schlüssel
+% zugewiesen wird.
+The value of the key is first passed to the Lua function
+\lua{string.match(value, match)}
+(\url{http://www.lua.org/manual/5.3/manual.html#pdf-string.match})
+before being assigned to the key.
+%
+% Du kannst das Attribut \lua{match} deshalb mit einer Pattern-Matching-
+% Zeichenkette konfigurieren, wie sie in Lua zu Einsatz kommt.
+You can therefore configure the \lua{match} attribute with a pattern
+matching string used in Lua.
+%
% Werfe einen Blick in das Lua-Handbuch, wie man Patterns schreibt.
Take a look at the Lua manual on how to write patterns
-(\url{http://www.lua.org/manual/5.3/manual.html#6.4.1})
+(\url{http://www.lua.org/manual/5.3/manual.html#6.4.1}).
-\InputLuaExample[firstline=4,lastline=6]{defs/attrs/match.lua}
+\InputLua[firstline=4,lastline=7]{defs/attrs/match/birthday.lua}
\noindent
% Kann das Pattern im Wert nicht gefunden werden, wird eine
% Fehlermeldung ausgegeben.
If the pattern cannot be found in the value, an error message is issued.
-\InputLuaExample[firstline=14,lastline=17]{defs/attrs/match.lua}
+\InputLua[firstline=15,lastline=18]{defs/attrs/match/birthday.lua}
\noindent
% Der Schlüssel erhält das Ergebnis der Funktion \lua{string.match(value,
@@ -867,8 +970,11 @@ If the pattern cannot be found in the value, an error message is issued.
The key receives the result of the function \lua{string.match(value,
match)}, which means that the original value may not be stored
completely in the key.
+%
+% Im nächsten Beispiel wird der gesamte Eingabewert akzeptiert:
+In the next example, the entire input value is accepted:
-\InputLuaExample[firstline=22,lastline=23]{defs/attrs/match.lua}
+\InputLua[firstline=4,lastline=5]{defs/attrs/match/year.lua}
\noindent
% Das Präfix “waste ” und das Suffix “ rubbisch” der Zeichenketten wird
@@ -876,7 +982,7 @@ completely in the key.
The prefix “waste ” and the suffix “ rubbisch” of the string are
discarded.
-\InputLuaExample[firstline=29,lastline=29]{defs/attrs/match.lua}
+\InputLua[firstline=11,lastline=11]{defs/attrs/match/year.lua}
\noindent
% Da Funktion \lua{string.match(value, match)} immer eine Zeichenkette
@@ -897,13 +1003,61 @@ The \lua{name} attribute allows an alternative notation of key names.
% Anstatt ...
Instead of ...
-\InputLuaExample[firstline=4,lastline=5]{defs/attrs/name.lua}
+\InputLua[firstline=4,lastline=8]{defs/attrs/name/as-key.lua}
\noindent
% ... können wir schreiben:
... we can write:
-\InputLuaExample[firstline=11,lastline=15]{defs/attrs/name.lua}
+\InputLua[firstline=4,lastline=8]{defs/attrs/name/name-attr.lua}
+
+%%
+%
+%%
+
+\subsubsection{Attribute “\texttt{pick}”}
+
+% Das Attribut \lua{pick} sucht nach einem Wert, der keinem Schlüssel
+% zugeordnet ist.
+The attribute \lua{pick} searches for a value not assigned to a key.
+% Der zuerst gefundene Wert, d. h. der weiter links stehende Wert, wird
+% einem Schlüssel zugewiesen.
+The first value found, i.e. the one further to the left, is assigned to
+a key.
+
+\InputLua[firstline=4,lastline=6]{defs/attrs/pick/dimension.lua}
+
+\noindent
+% Es wird nur in der aktuellen Ergebnistabelle gesucht und nicht auf
+% anderen Ebenen in der rekursiven Datenstruktur.
+Only the current result table is searched, not other levels in the
+recursive data structure.
+
+\InputLua[firstline=4,lastline=11]{defs/attrs/pick/different-levels.lua}
+
+\noindent
+% Die Suche nach Werte wird aktiviert, wenn das Attribut \lua{pick} auf
+% \lua{true} gesetzt wird.
+The search for values is activated when the attribute \lua{pick} is set
+to \lua{true}.
+% Die Suche kann eingeschränkt werden, indem ein Datentype angegeben
+% wird.
+The search can be limited by specifying a data type.
+% Nach diesen Datentypen kann gesucht werden:
+These data types can be searched for:
+\directlua{
+ local types = {}
+ for t, fn in pairs(luakeys.is) do
+ table.insert(types, t)
+ end
+ tex.print(table.concat(types, ', '))
+}.
+
+% Wird einem Schlüssel bereits bei der Eingabe ein Wert zugewiesen, dann
+% wird nicht weiter nach Werten gesucht.
+If a value is already assigned to a key when it is entered, then no
+further search for values is performed.
+\InputLua[firstline=4,lastline=8]{defs/attrs/pick/value-set.lua}
%%
%
@@ -912,19 +1066,24 @@ Instead of ...
\subsubsection{Attribute “\texttt{process}”}
\label{attr-process}
-The \lua{process} attribute can be used to define a function whose return
-value is passed to the key. Four parameters are passed when the
-function is called:
+% Das Attribut \lua{process} kann dazu verwendet werden, um eine Funktion
+% zu definieren, deren Rückgabewert an den Schlüssel übergeben wird.
+The \lua{process} attribute can be used to define a function whose
+return value is passed to the key.
+%
+% Beim Aufruf der Funktion werden vier Parameter übergeben:
+Four parameters are passed when the function is called:
\begin{enumerate}
\item \lua{value}:
-% Der zum schlüssel gehörende aktuelle Wert.
+% Der zum Schlüssel gehörende aktuelle Wert.
The current value asssociated with the key.
\item \lua{input}:
% Die Ergebnis-Tabelle, die vor dem Zeitpunkt geklont wurde, als mit dem
% Anwenden der Definitionen begonnen wurde.
-The result table cloned before the time the definitions started to be applied.
+The result table cloned before the time the definitions started to be
+applied.
\item \lua{result}: The table in which the final result will be saved.
@@ -932,26 +1091,29 @@ The result table cloned before the time the definitions started to be applied.
are stored.
\end{enumerate}
-% Das folgende Beispiel demonstriert den Parameter \lua{value}.
\noindent
+% Das folgende Beispiel demonstriert den Parameter \lua{value}:
The following example demonstrates the \lua{value} parameter:
-\InputLuaExample[firstline=4,lastline=14]{defs/attrs/process.lua}
+\InputLua[firstline=4,lastline=14]{defs/attrs/process/parameter-value.lua}
\noindent
+% Das folgende Beispiel demonstriert den Parameter \lua{input}:
The following example demonstrates the \lua{input} parameter:
-\InputLuaExample[firstline=22,lastline=34]{defs/attrs/process.lua}
+\InputLua[firstline=4,lastline=16]{defs/attrs/process/parameter-input.lua}
\noindent
+% Das folgende Beispiel demonstriert den Parameter \lua{result}:
The following example demonstrates the \lua{result} parameter:
-\InputLuaExample[firstline=42,lastline=50]{defs/attrs/process.lua}
+\InputLua[firstline=4,lastline=12]{defs/attrs/process/parameter-result.lua}
\noindent
+% Das folgende Beispiel demonstriert den Parameter \lua{unknown}:
The following example demonstrates the \lua{unknown} parameter:
-\InputLuaExample[firstline=58,lastline=65]{defs/attrs/process.lua}
-\InputLuaExample[firstline=69,lastline=69]{defs/attrs/process.lua}
+\InputLua[firstline=4,lastline=11]{defs/attrs/process/parameter-unknown.lua}
+\InputLua[firstline=15,lastline=15]{defs/attrs/process/parameter-unknown.lua}
%%
%
@@ -959,16 +1121,41 @@ The following example demonstrates the \lua{unknown} parameter:
\subsubsection{Attribute “\texttt{required}”}
-\InputLuaExample[firstline=4,lastline=5]{defs/attrs/required.lua}
+% Durch das Attribut \lua{required} kann erzwungen werden, dass ein
+% bestimmter Schlüssel angegeben werden muss.
+The \lua{required} attribute can be used to enforce that a specific key
+must be specified.
+%
+% Im untenstehenden Beispiel wird der Schlüssel \lua{important} als
+% zwingend notwendig definiert.
+In the example below, the key \lua{important} is defined as mandatory.
-\InputLuaExample[firstline=13,lastline=14]{defs/attrs/required.lua}
+\InputLua[firstline=4,lastline=5]{defs/attrs/required.lua}
+
+\noindent
+% Fehlt der Schlüssel \lua{important} in der Eingabe, so tritt eine
+% Fehlermeldung auf.
+If the key \lua{important} is missing in the input, an error message
+occurs.
+
+\InputLua[firstline=13,lastline=14]{defs/attrs/required.lua}
\noindent
A recursive example:
-\InputLuaExample[firstline=18,lastline=23]{defs/attrs/required.lua}
-\InputLuaExample[firstline=29,lastline=30]{defs/attrs/required.lua}
-\InputLuaExample[firstline=38,lastline=39]{defs/attrs/required.lua}
+\InputLua[firstline=18,lastline=23]{defs/attrs/required.lua}
+
+\noindent
+% Der Schlüssel \lua{important2} auf der Ebene 2 fehlt.
+The \lua{important2} key on level 2 is missing.
+
+\InputLua[firstline=29,lastline=30]{defs/attrs/required.lua}
+
+\noindent
+% Der Schlüssel \lua{important1} auf der untersten Schlüssel-Ebene fehlt.
+The \lua{important1} key at the lowest key level is missing.
+
+\InputLua[firstline=38,lastline=39]{defs/attrs/required.lua}
%%
%
@@ -981,39 +1168,39 @@ A recursive example:
The \lua{sub_keys} attribute can be used to build nested key-value pair
definitions.
-\InputLuaExample[firstline=4,lastline=16]{defs/attrs/sub-keys.lua}
+\InputLua[firstline=4,lastline=16]{defs/attrs/sub-keys.lua}
%-----------------------------------------------------------------------
%
%-----------------------------------------------------------------------
-\subsection{Function \texttt{render(result): string}}
+\subsection{Function “\texttt{render(result): string}”}
The function \lua{render(result)} reverses the function
\lua{parse(kv_string)}. It takes a Lua table and converts this table
into a key-value string. The resulting string usually has a different
order as the input table.
-\InputLuaExample[firstline=4,lastline=10]{functions/render.lua}
+\InputLua[firstline=4,lastline=10]{functions/render.lua}
\noindent
In Lua only tables with 1-based consecutive integer keys (a.k.a. array
tables) can be parsed in order.
-\InputLuaExample[firstline=16,lastline=17]{functions/render.lua}
+\InputLua[firstline=16,lastline=17]{functions/render.lua}
%%
%
%%
-\subsection{Function \texttt{debug(result): void}}
+\subsection{Function “\texttt{debug(result): void}”}
The function \lua{debug(result)} pretty prints a Lua table to standard
output (stdout). It is a utility function that can be used to debug and
inspect the resulting Lua table of the function \lua{parse}. You have to
compile your \TeX{} document in a console to see the terminal output.
-\InputLuaExample[firstline=4,lastline=5]{functions/debug.lua}
+\InputLua[firstline=4,lastline=5]{functions/debug.lua}
\noindent
The output should look like this:
@@ -1032,7 +1219,7 @@ The output should look like this:
%
%%
-\subsection{Function \texttt{save(identifier, result): void}}
+\subsection{Function “\texttt{save(identifier, result): void}”}
The function \lua{save(identifier, result)} saves a result (a
table from a previous run of \lua{parse}) under an identifier.
@@ -1043,7 +1230,7 @@ store results for the later usage.
%
%%
-\subsection{Function \texttt{get(identifier): result}}
+\subsection{Function “\texttt{get(identifier): result}”}
The function \lua{get(identifier)} retrieves a saved result from the
result store.
@@ -1052,22 +1239,105 @@ result store.
%
%%
-\subsection{Table \texttt{is}}
+\subsection{Table “\texttt{is}”}
+
+% In der Tabelle \lua{is} werden einige Funktionen zusammengefasst, die
+% überprüft ob eine Eingabe einem bestimmen Datentyp entspricht.
+In the table \lua{is} some functions are summarized, which check whether
+an input corresponds to a certain data type.
+%
+% Alle Funktionen akzeptieren nicht nur die entsprechenden Lua-Datentypen,
+% sondern auch Eingaben als Zeichenketten.
+All functions accept not only the corresponding Lua data types, but also
+input as strings.
+%
+% Beispielsweise wird die Zeichenkette \lua{'true'} von der
+% \lua{is.boolean()}-Funktion als Wahrheitswert erkannt.
+For example, the string \lua{'true'} is recognized by the
+\lua{is.boolean()} function as a boolean value.
+
+\subsubsection{Function “\texttt{is.boolean(value): boolean}”}
+\InputLua[firstline=6,lastline=23]{functions/is/boolean.lua}
+
+\subsubsection{Function “\texttt{is.dimension(value): boolean}”}
+\InputLua[firstline=6,lastline=16]{functions/is/dimension.lua}
+
+\subsubsection{Function “\texttt{is.integer(value): boolean}”}
+\InputLua[firstline=6,lastline=11]{functions/is/integer.lua}
+
+\subsubsection{Function “\texttt{is.number(value): boolean}”}
+\InputLua[firstline=6,lastline=13]{functions/is/number.lua}
+
+\subsubsection{Function “\texttt{is.string(value): boolean}”}
+\InputLua[firstline=6,lastline=12]{functions/is/string.lua}
+
+%%
+%
+%%
+
+\subsection{Table “\texttt{utils}”}
+
+\subsubsection{Function “\texttt{utils.scan_oarg(initial_delimiter?, end_delimiter?): string}”}
-\subsubsection{Function \texttt{is.boolean(value): boolean}}
-\InputLuaExample[firstline=7,lastline=23]{is-table.lua}
+% Plain \TeX{} kennt keine optionalen Argumente (oarg).
+Plain \TeX{} does not know optional arguments (oarg).
+%
+% Die Funktion ermöglicht es nicht nur in \LaTeX{}, sondern auch in
+% Plain \TeX{} nach optionalen Argumenten zu suchen.
+The function \\ \lua{utils.scan_oarg(initial_delimiter?,
+end_delimiter?): string} allows to search for optional arguments not only
+in \LaTeX{} but also in Plain \TeX.
+%
+% Die Funktion basiert auf der Token-Bibliothek.
+The function uses the token library built into Lua\TeX{}.
+%
+% Die beiden Parameter \lua{initial_delimiter} und \lua{end_delimiter}
+% können weggelassen werden.
+The two parameters \lua{initial_delimiter} and \lua{end_delimiter} can
+be omitted.
+%
+% Dann werden eckige Klammern als Begrenzungszeichen angenommen.
+Then square brackets are assumed to be delimiters.
+%
+% Dieser Lua-Code \lua{utils.scan_oarg('(', ')')} sucht beispielsweise
+% nach an einem optionalen Argument in runden Klammern.
+For example, this Lua code \lua{utils.scan_oarg('(', ')')} searches for
+an optional argument in round brackets
+%
+% Die Funktion gibt die Zeichenkette zwischen den Begrenzungszeichen
+% zurück, oder nil wenn Begrenzungszeichen gefunden werden konnten.
+The function returns the string between the delimiters or \lua{nil} if
+no delimiters could be found.
+%
+% Die Begrenzungszeichen sind im Ergebnis nicht enthalten.
+The delimiters themselves are not included in the result.
+%
+% Nach dem \latex{\directlua{}} darf das Makro, indem
+% \lua{utils.scan_oarg} eingesetzt wird, zu keinen Zeichen expandieren.
+After the \latex{\directlua{}}, the macro using \lua{utils.scan_oarg}
+must not expand to any characters.
-\subsubsection{Function \texttt{is.dimension(value): boolean}}
-\InputLuaExample[firstline=27,lastline=37]{is-table.lua}
+\InputLatex{utils/scan-oarg-plain.tex}
-\subsubsection{Function \texttt{is.integer(value): boolean}}
-\InputLuaExample[firstline=41,lastline=46]{is-table.lua}
+%%
+%
+%%
+
+\subsection{Table “version”}
-\subsubsection{Function \texttt{is.number(value): boolean}}
-\InputLuaExample[firstline=50,lastline=57]{is-table.lua}
+% Das luakeys Projekt verwendet semantic versioning
+The luakeys project uses semantic versioning.
+% Die drei Versionenzahlen des Semantic Versioning Schemas werden in
+% einer Tabelle in der Reihenfolge MAJOR, MINOR, PATCH als Ganzzahlen
+% abgelegt.
+The three version numbers of the semantic versioning scheme are stored
+in a table as integers in the order MAJOR, MINOR, PATCH.
+% Mit Hilfe dieser Tabelle kann überprüft werden, ob die richtige
+% Version installiert ist.
+This table can be used to check whether the correct version is
+installed.
-\subsubsection{Function \texttt{is.string(value): boolean}}
-\InputLuaExample[firstline=61,lastline=67]{is-table.lua}
+\InputLua[firstline=4,lastline=10]{version.lua}
%-----------------------------------------------------------------------
%
@@ -1128,10 +1398,12 @@ key-value lists (\texttt{level1=\{level2=\{key=value,naked\}\}}).
\alt `ex' | `EX'
\alt `in' | `IN'
\alt `mm' | `MM'
+ \alt `mu' | `MU'
\alt `nc' | `NC'
\alt `nd' | `ND'
\alt `pc' | `PC'
\alt `pt' | `PT'
+ \alt `px' | `PX'
\alt `sp' | `SP'
<boolean> ::= <boolean-true> | <boolean-false>
@@ -1156,16 +1428,10 @@ into Lua’s boolean type \lua{true}, the strings \texttt{false},
\texttt{FALSE} and \texttt{False} into \lua{false}.
\begin{multicols}{2}
-\begin{minted}{latex}
-\luakeysdebug{
- lower case true = true,
- upper case true = TRUE,
- title case true = True
- lower case false = false,
- upper case false = FALSE,
- title case false = False,
-}
-\end{minted}
+\InputLatex[firstline=5,lastline=12]{luakeysdebug/boolean-latex.tex}
+
+\columnbreak
+
\begin{minted}{lua}
{
['lower case true'] = true,
@@ -1185,18 +1451,19 @@ into Lua’s boolean type \lua{true}, the strings \texttt{false},
\subsubsection{number}
\begin{multicols}{2}
-\begin{minted}{latex}
-\luakeysdebug{
- num1 = 4,
- num2 = -4,
- num3 = 0.4
-}
-\end{minted}
+\InputLatex[firstline=5,lastline=13]{luakeysdebug/number-latex.tex}
+
+\columnbreak
+
\begin{minted}{lua}
{
- ['num1'] = 4,
- ['num2'] = -4,
- ['num3'] = 0.4
+ ['num0'] = 42,
+ ['num1'] = 42,
+ ['num2'] = -42,
+ ['num3'] = 4.2,
+ ['num4'] = 0.42,
+ ['num5'] = 0.42,
+ ['num6'] = '0 . 42', -- string
}
\end{minted}
\end{multicols}
@@ -1207,6 +1474,22 @@ into Lua’s boolean type \lua{true}, the strings \texttt{false},
\subsubsection{dimension}
+% Luakeys versucht alle Einheiten zu erkennen, die in der TeX-Welt
+% verwendet werden.
+|luakeys| tries to recognize all units used in the \TeX{} world.
+%
+% Nach dem Lua\TeX-Quellcode .
+According to the Lua\TeX{} source code
+(\href{https://github.com/TeX-Live/luatex/blob/51db1985f5500dafd2393aa2e403fefa57d3cb76/source/texk/web2c/luatexdir/lua/ltexlib.c#L434-L625}
+{source/texk/web2c/luatexdir/lua/ltexlib.c})
+%
+% und nach dem Dimensionen-Modul der lulibs-Bibliothek
+and the dimension module of the lualibs library
+(\href{https://raw.githubusercontent.com/latex3/lualibs/master/lualibs-util-dim.lua}
+{lualibs-util-dim.lua}),
+%
+% müssten alle Einheiten erkannt werden
+all units should be recognized.
\begin{multicols}{3}
\tiny
\begin{center}
@@ -1221,33 +1504,19 @@ em & horizontal measure of \emph{M} \\
ex & vertical measure of \emph{x} \\
in & inch \\
mm & milimeter \\
+mu & math unit \\
nc & new cicero \\
nd & new didot \\
pc & pica \\
pt & point \\
+px & x height current font \\
sp & scaledpoint \\
\end{tabular}
\end{center}
\columnbreak
-\begin{minted}{latex}
-\luakeysdebug{
- bp = 1bp,
- cc = 1cc,
- cm = 1cm,
- dd = 1dd,
- em = 1em,
- ex = 1ex,
- in = 1in,
- mm = 1mm,
- nc = 1nc,
- nd = 1nd,
- pc = 1pc,
- pt = 1pt,
- sp = 1sp,
-}
-\end{minted}
+\InputLatex[firstline=5,lastline=21]{luakeysdebug/dimension/all-latex.tex}
\columnbreak
@@ -1261,15 +1530,39 @@ sp & scaledpoint \\
['ex'] = 282460,
['in'] = 4736286,
['mm'] = 186467,
+ ['mu'] = 65536,
['nc'] = 839105,
['nd'] = 69925,
['pc'] = 786432,
['pt'] = 65536,
+ ['px'] = 65781,
['sp'] = 1,
}
\end{minted}
\end{multicols}
+\noindent
+% Im nächsten Beispiel werden die unterschiedlichen Notationsformen der
+% Dimensionen illustriert.
+The next example illustrates the different notations of the dimensions.
+
+\begin{multicols}{2}
+\InputLatex[firstline=5,lastline=12]{luakeysdebug/dimension/notations-latex.tex}
+
+\columnbreak
+
+\begin{minted}{lua}
+{
+ ['upper'] = 1864679,
+ ['lower'] = 1864679,
+ ['space'] = 1864679,
+ ['plus'] = 1864679,
+ ['minus'] = -1864679,
+ ['nodim'] = '1 c m', -- string
+}
+\end{minted}
+\end{multicols}
+
%%
%
%%
@@ -1287,7 +1580,7 @@ With or without double quotes.
If the text have to contain commas, curly braces or equal signs, then
double quotes must be used.
-\InputLuaExample[firstline=4,lastline=17]{data-types/string.lua}
+\InputLua[firstline=4,lastline=17]{data-types/string.lua}
\subsubsection{Naked keys}
@@ -1303,14 +1596,14 @@ and stored into an array.
% Index ist 1).
In Lua an array is a table with numeric indexes (The first index is 1).
-\InputLatexExample[firstline=5,lastline=12]{luakeysdebug/naked-keys.tex}
+\InputLatex[firstline=5,lastline=12]{luakeysdebug/naked-keys-latex.tex}
\noindent
% VAlle erkannten Datentypen können als eigenständige Werte verwendet
% werden.
All recognized data types can be used as standalone values.
-\InputLatexExample[firstline=14,lastline=19]{luakeysdebug/naked-keys.tex}
+\InputLatex[firstline=14,lastline=19]{luakeysdebug/naked-keys-latex.tex}
%-----------------------------------------------------------------------
%
@@ -1320,6 +1613,10 @@ All recognized data types can be used as standalone values.
\section{Examples}
+%%
+%
+%%
+
\subsection{Extend and modify keys of existing macros}
Extend the includegraphics macro with a new key named \latex{caption}
@@ -1327,17 +1624,34 @@ and change the accepted values of the \latex{width} key. A number
between 0 and 1 is allowed and converted into
\latex{width=0.5\linewidth}
-\InputLuaExample{extend-includegraphics/extend-keys.lua}
-\InputLatexExample{extend-includegraphics/extend-keys.tex}
+\InputLua{extend-includegraphics/extend-keys.lua}
+\InputLatex{extend-includegraphics/extend-keys-latex.tex}
+
+%%
+%
+%%
\subsection{Process document class options}
-\begin{minted}{latex}
-\directlua{luakeys.parse('\@classoptionslist')}
-\end{minted}
+% Auf die Optionen einer \LaTeX{} Dokumentenklasse kann über das Macro
+% \latex{\@classoptionslist} zu gegriffen werden.
+The options of a \LaTeX{} document class can be accessed via the
+\latex{\@classoptionslist} macro.
+%
+% Die Zeichenkette des Makros \latex{\@classoptionslist} ist bereits
+% expandiert und normalisiert.
+The string of the macro \latex{\@classoptionslist} is already expanded
+and normalized.
+%
+% Neben Leerzeichen werden auch die geschweiften Klammern entfernt.
+In addition to spaces, the curly brackets are also removed.
+% Es ist deshalb nicht möglich, in einander geschachtelte hierarische
+% Schlüssel-Wert-Paare über die Option zu verarbeiten.
+It is therefore not possible to process nested hierarchical key-value
+pairs via the option.
-\InputLatexExample{class-options/test-class.cls}
-\InputLatexExample{class-options/use-test-class.tex}
+\InputLatex{class-options/test-class.cls}
+\InputLatex{class-options/use-test-class-latex.tex}
\begin{minted}{lua}
{
@@ -1458,30 +1772,30 @@ An example of how to use the command in \LaTeX:
\inputminted[linenos=true]{latex}{luakeys-debug.sty}
-\changes{v0.1}{2021/01/18}{Inital release}
-\changes{v0.2}{2021/09/19}{
+\changes{0.1.0}{2021/01/18}{Inital release}
+\changes{0.2.0}{2021/09/19}{
* Allow all recognized data types as keys
* Allow TeX macros in the values
* New public Lua functions: save(identifier, result), get(identifier)
}
-\changes{v0.3}{2021/11/05}{
+\changes{0.3.0}{2021/11/05}{
* Add a LuaLaTeX wrapper “luakeys.sty”
* Add a plain LuaTeX wrapper “luakeys.tex”
* Rename the previous documentation file “luakeys.tex” to luakeys-doc.tex”
}
-\changes{v0.4}{2021/12/31}{
+\changes{0.4.0}{2021/12/31}{
* Parser: Add support for nested tables (for example {{'a', 'b'}})
* Parser: Allow only strings and numbers as keys
* Parser: Remove support from Lua numbers with exponents (for example '5e+20')
* Switch the Lua testing framework to busted
}
-\changes{v0.5}{2022/04/04}{
+\changes{0.5.0}{2022/04/04}{
* Add possibility to change options globally
* New option: standalone_as_true
* Add a recursive converter callback / hook to process the parse tree
* New option: case_insensitive_keys
}
-\changes{v0.6}{2022/06/09}{
+\changes{0.6.0}{2022/06/09}{
* New feature: keys now can be defined using the function
“define(defs, opts)” or “define(kv_string, { defs = { key = { ... } } })”
* Rename the global options table from “default_options” to “opts”
@@ -1494,6 +1808,14 @@ An example of how to use the command in \LaTeX:
produce the previous effect.
* The function “print()” is now called “debug()”
}
+\changes{0.7.0}{2022/07/06}{
+* The project now uses semantic versioning.
+* New definition attribute “pick” to pick standalone values and assign
+ them to a key
+* New function “utils.scan_oarg()” to search for an optional argument,
+ that means scan for tokens that are enclosed in square brackets
+* extend and improve documentation
+}
\pagebreak
\PrintChanges
\pagebreak