summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--luatexbase-attr.dtx71
1 files changed, 44 insertions, 27 deletions
diff --git a/luatexbase-attr.dtx b/luatexbase-attr.dtx
index 759c5a7..341feb2 100644
--- a/luatexbase-attr.dtx
+++ b/luatexbase-attr.dtx
@@ -131,10 +131,41 @@ and the derived files
% \maketitle
%
% \begin{abstract}
+% In addition to the registers existing in \tex and \etex, \luatex introduces
+% a new concept: attributes. This package takes care of attribute allocation
+% just like Plain TeX and LaTeX do for other registers.
% \end{abstract}
%
% \section{Documentation}
%
+% The main macro defined here is |\newluatexattribute|. It behaves in the same
+% way as |\newcount|. There are also two helper macros: |\setluatexattibute|
+% sets an attribute's value (locally, but you can use |\global| in front of
+% it). |\unsetluatexattribute| unsets an atribute by giving it a special
+% value, depending on \luatex's version; you should always use this macro
+% in order to be sure the correct special value for your version of \luatex is
+% used.
+%
+% Due to the intended use of attributes, it makes no sense to locally
+% allocate an attribute the way you can locally allocate a counter using
+% \file{etex.sty}'s |\loccount|, so no corresponding macro is defined.
+%
+% The various Lua functions for manipulating attributes use a number to
+% designate the attribute. Hence, package writers need a way to know the
+% number of the attribute associated to |\fooattr| assuming it was defined
+% using |\newluatexattribute\fooattr|, something that \luatex currently
+% doesn't support (you can get the current value of the associated attribute
+% as |tex.atrribute.fooattr|, but not the attribute number).
+%
+% There are several ways to work around this. For example, it is possible to
+% extract the number at any time from the |\meaning| of |\foobar|.
+% Alternatively, one could look at |\the\allocationnumber| just after the
+% definition of |\fooattr| and remember it in a Lua variable. For your
+% convenience, this is automatically done by |\newluatexattribute|: the number
+% is remembered in a dedicated Lua table so that you can get it as
+% |luatextra.attributes.foobar| (mind the absence of backslash here) at any
+% time.
+%
% \section{Implementation}
%
% \subsection{\tex package}
@@ -205,10 +236,7 @@ and the derived files
\directlua{dofile(kpse.find_file('luatexbase.attr.lua', 'lua'))}
% \end{macrocode}
%
-% The most important macro here is |\newluatexattribute| that allocates a
-% new attribute, and adds it in the |tex.attributename| table (see
-% |luatextra.attributedef_from_tex| for more details. It works just like
-% the other |\new*| macros, to $65536$ attributes can be allocated.
+% The allocaton macro.
%
% \begin{macrocode}
\newcount\lltxb@attribute@alloc
@@ -230,15 +258,9 @@ and the derived files
\fi}
% \end{macrocode}
%
-% Two convenient macros, one to set an attribute (basically just a
-% wrapper), and another one to unset it. Unsetting attributes with this
-% function is important, as the \texttt{unset} value may change, as it
-% already has in \luatex $0.37$.
+% Helper macro |\unsetluatexattribute|: depends on \luatex's version.
%
% \begin{macrocode}
-\def\setluatexattribute#1#2{%
- #1=\numexpr#2\relax
-}
\def\unsetluatexattribute#1{%
\ifnum\luatexversion<37\relax
#1=-1\relax
@@ -247,6 +269,15 @@ and the derived files
\fi}
% \end{macrocode}
%
+% And now the trivial helper macro.
+%
+% \begin{macrocode}
+\def\setluatexattribute#1#2{%
+ #1=\numexpr#2\relax}
+% \end{macrocode}
+%
+% That's all folks!
+%
% \begin{macrocode}
\lltxb@attr@AtEnd
%</texpackage>
@@ -256,26 +287,12 @@ and the derived files
%
% \begin{macrocode}
%<*luamodule>
+module('luatextra', package.seeall)
% \end{macrocode}
%
-% Attribute allocation is done mainly in the \file{.sty} file, but there
-% is also a Lua addition for attribute handling: \luatex is by default
-% unable to tell the attribute number corresponding to an attribute name.
-% This attribute number is necessary for functions such as
-% |node.has_attribute|, which is used very often. The solution
-% until now was to give a chosen attribute number to each attribute, and
-% pray that someone else didn't use it before. With this method it was easy
-% to know the number of an attribute, as it was chosen. Now with the
-% |\newluaattribute| macro, it's impossible to know the
-% number of an attribute. To fix it, when |\newluaattribute|
-% is called, it calls |luatextra.attributedef_from_tex|. This
-% function registers the number in the table |tex.attributenumber|.
-% For example to get the number of the attribute |myattribute|
-% registered with |\newluaattribute\myattribute|, you
-% can simply call |tex.attributenumber[myattribute]|.
+% Record the allocation number in a Lua table.
%
% \begin{macrocode}
-module('luatextra', package.seeall)
attributes = {}
tex.attributenumber = attributes
function attributedef_from_tex(name, number)