From 8d09d32f29c87ec1808542705776d35e9de2583e Mon Sep 17 00:00:00 2001
From: Joseph Wright <joseph.wright@morningstar2.co.uk>
Date: Fri, 2 Oct 2020 13:17:49 +0100
Subject: [PATCH] Add some design comments

---
 base/ltzref.dtx | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/base/ltzref.dtx b/base/ltzref.dtx
index 0d556d13c..793e15adf 100644
--- a/base/ltzref.dtx
+++ b/base/ltzref.dtx
@@ -52,6 +52,36 @@
 % The names of labels and attributes may be arbitrary. Note that there is
 % a single namespace for each.
 %
+% \subsection{Design discussion}
+%
+% The design here largely follows ideas from \pkg{zref}. In patrticular, there
+% are two independent concepts: attributes that can be recorded between runs,
+% and labels which consist of lists of these attributes. The reason for the
+% split is that individual labels will want to record some but not all
+% attributes. For examples, a label concerned with position would track
+% the $x$ and $y$ co-ordinates of the current point, but not for example
+% the page number.
+%
+% In the current implementation, attributes share a single namespace. This
+% allows multiple lists to re-use the same attribute, for example page number,
+% absolute page number, etc. This does mean that \emph{changing} a standard
+% attribute is an issue. However, some attributes have complex definitions
+% (again, see \pkg{zref} at present): having them in a single shared space
+% avoids the need to copy code.
+%
+% Labels could be implemented as |prop| data. That is not done at present as
+% there is no obvious need to map to or copy the data. As such, faster
+% performance is available using a hash table approach as in a \enquote{classical}
+% set up. Data written to the |.aux| file uses simple paired \emph{balanced
+% text} not keyvals: this avoids any restrictions on names and again offers
+% increased performance.
+%
+% We likely need to think about the use of \tn{@bsphack}/\tn{@esphack}, which
+% live at the document command level. We also should look at how changes here
+% impact on the main \cs{label} and \cs{ref} commands. In particular, note that
+% the referencing command here is expandable, which makes issuing a rerun warning
+% more challenging.
+%
 % \subsection{Code interfaces}
 %
 % \begin{function}{\ref_attribute_gset:nnnn}