[latex3-commits] [git/LaTeX3-latex3-latex3] l3bitset-2: clarify documentation regarding names / index (7e02389e0)

[Ulrike Fischer]

Repository : https://github.com/latex3/latex3
On branch  : l3bitset-2
Link       : https://github.com/latex3/latex3/commit/7e02389e074f0f4fd28749bbd8151bd41bcb6be7

>---------------------------------------------------------------

commit 7e02389e074f0f4fd28749bbd8151bd41bcb6be7
Author: Ulrike Fischer <fischer at troubleshooting-tex.de>
Date:   Tue Jan 26 19:51:48 2021 +0100

    clarify documentation regarding names / index


>---------------------------------------------------------------

7e02389e074f0f4fd28749bbd8151bd41bcb6be7
 l3experimental/l3bitset/l3bitset.dtx | 49 ++++++++++++++++++++----------------
 1 file changed, 27 insertions(+), 22 deletions(-)

diff --git a/l3experimental/l3bitset/l3bitset.dtx b/l3experimental/l3bitset/l3bitset.dtx
index 029fd1504..c1df5e3a9 100644
--- a/l3experimental/l3bitset/l3bitset.dtx
+++ b/l3experimental/l3bitset/l3bitset.dtx
@@ -49,7 +49,10 @@
 %
 % This package defines and implements the data type \texttt{bitset}, a vector of
 % bits. The size of the vector may grow dynamically.
-% Individual bits can be set and unset by index and by name.
+% Individual bits can be set and unset by names pointing to an index position.
+% The names |1|, |2|, |3|, \ldots\ are predeclared and point to the
+% index positions  $1$, $2$, $3$,\ldots. More names can be added and existing names can
+% be changed.
 % The index is like all other indices in \pkg{expl3} modules \emph{1-based}.
 % A \texttt{bitset} can be output as binary number or---as needed e.g. in a
 % PDF dictionary---as decimal (arabic) number.
@@ -91,13 +94,16 @@
 % The name--index pairs given in the second
 % argument of \cs{bitset_new:Nn} declares names for some indices,
 % which can be used to set and unset bits.
+% The names |1|, |2|, |3|, \ldots\ are predeclared and point to the
+% index positions $1$, $2$, $3$, \ldots.
 %
-% \meta{index\ldots} should be a positive number.
-% It can be an \meta{integer expression} which evaluates to a positive number.
+% \meta{index\ldots} should be a positive number or an
+% \meta{integer expression} which evaluates to a positive number.
 % The expression is evaluated when the index is used, not a declaration time.
 % The names \meta{name\ldots}
-% should be unique. Using a number as name, e.g.~|10=1|, is allowed,
-% but the index position |10| can then only be reached if some other
+% should be unique. Using a number as name, e.g.~|10=1|, is allowed, it
+% then overwrites the predeclared name |10|,
+% but the index position $10$ can then only be reached if some other
 % name for it exists, e.g. |ten=10|.
 % It is not necessary to give every index
 % a name, and an index can have more than one name. The named index
@@ -137,7 +143,7 @@
 %      print = 3
 %    }
 %  \end{verbatim}
-%  it is possible to set bit 3 by using any of this alternatives:
+%  it is possible to set bit $3$ by using any of this alternatives:
 %  \begin{verbatim}
 %  \bitset_set_true:Nn \l_pdfannot_F_bitset {Print}
 %  \bitset_set_true:Nn \l_pdfannot_F_bitset {print}
@@ -159,13 +165,12 @@
 % \begin{function}[added = 2021-01-26]
 %   { \bitset_set_true:Nn, \bitset_set_true:cn, \bitset_gset_true:Nn, \bitset_gset_true:cn  }
 %   \begin{syntax}
-%     \cs{bitset_set_true:Nn}   \meta{bitset var}  \Arg{name/index}\\
-%     \cs{bitset_gset_true:Nn}  \meta{bitset var}  \Arg{name/index}
+%     \cs{bitset_set_true:Nn}   \meta{bitset var}  \Arg{name}\\
+%     \cs{bitset_gset_true:Nn}  \meta{bitset var}  \Arg{name}
 %   \end{syntax}
-% This sets the bit of the index position represented by \Arg{name/index} to $1$.
-% \Arg{name/index} should be either a declared name or a positive,
-% unsigned explicit integer (not an integer expression).
-% If it is both a name and a number, the name will take precedence.
+% This sets the bit of the index position represented by \Arg{name} to $1$.
+% \Arg{name} should be either one of the predeclared names
+% |1|, |2|, |3|, \ldots, or one of the names added manually.
 % Index position are 1-based.
 % If needed the length of the bit vector is enlarged.
 % \end{function}
@@ -173,18 +178,17 @@
 % \begin{function}[added = 2021-01-26]
 %   { \bitset_set_false:Nn, \bitset_set_false:cn, \bitset_gset_false:Nn, \bitset_set_false:cn }
 %   \begin{syntax}
-%     \cs{bitset_set_false:Nn}   \meta{bitset var}  \Arg{name/index}\\
-%     \cs{bitset_gset_false:Nn}  \meta{bitset var}  \Arg{name/index}
+%     \cs{bitset_set_false:Nn}   \meta{bitset var}  \Arg{name}\\
+%     \cs{bitset_gset_false:Nn}  \meta{bitset var}  \Arg{name}
 %   \end{syntax}
-% This unsets the bit of the index position represented by \Arg{name/index} (sets
+% This unsets the bit of the index position represented by \Arg{name} (sets
 % it to $0$).
-% \Arg{name/index} should be either a declared name or a positive,
-% unsigned explicit integer (not an integer expression).
-% If it is both a name and a number, the name will take precedence.
+% \Arg{name} should be either one of the predeclared names
+% |1|, |2|, |3|, \ldots, or one of the names added manually.
 % The index is $1$-based. If the index position is larger
 % than the current length of the bit vector
 % nothing happens. If the leading (left most) bit is unset,
-% zeros are not trimmed but stay in the bit vector and a still shown
+% zeros are not trimmed but stay in the bit vector and are still shown
 % by \cs{bitset_show:N}.
 % \end{function}
 %
@@ -202,11 +206,12 @@
 % \begin{function}[EXP,added = 2021-01-26]
 %   { \bitset_item:Nn, \bitset_item:cn }
 %   \begin{syntax}
-%     \cs{bitset_item:Nn}   \meta{bitset var}  \Arg{name/index}
+%     \cs{bitset_item:Nn}   \meta{bitset var}  \Arg{name}
 %   \end{syntax}
 % \cs{bitset_item:Nn} outputs \texttt{1} if the bit with
-% the index number represented by \Arg{name/index} is set and \texttt{0} otherwise.
-%  \Arg{name/index} is a declared name or a positive, unsigned explicit number.
+% the index number represented by \Arg{name} is set and \texttt{0} otherwise.
+%  \Arg{name} is either one of the predeclared names
+% |1|, |2|, |3|, \ldots, or one of the names added manually.
 % \end{function}
 %
 % \begin{function}[EXP,added = 2021-01-26]