From ded55718c96e299414c7688764a8d0d045a2fa44 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Sat, 20 Aug 2016 21:38:17 +0000
Subject: listofitems (20aug16)

git-svn-id: svn://tug.org/texlive/trunk@41895 c570f23f-e606-0410-a88d-b1316a301751
---
 .../doc/generic/listofitems/listofitems-en.tex     | 487 +++++++++++++++++++++
 1 file changed, 487 insertions(+)
 create mode 100644 Master/texmf-dist/doc/generic/listofitems/listofitems-en.tex

(limited to 'Master/texmf-dist/doc/generic/listofitems/listofitems-en.tex')

diff --git a/Master/texmf-dist/doc/generic/listofitems/listofitems-en.tex b/Master/texmf-dist/doc/generic/listofitems/listofitems-en.tex
new file mode 100644
index 00000000000..0b2d7c5b5b0
--- /dev/null
+++ b/Master/texmf-dist/doc/generic/listofitems/listofitems-en.tex
@@ -0,0 +1,487 @@
+% This is the AMERICAN ENGLISH package documentation for "listofitems"
+\documentclass[american]{article}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{listofitems,babel,xspace}
+\usepackage[bottom]{footmisc}
+\usepackage{libertine}\usepackage[libertine]{newtxmath}
+\usepackage[scaled=0.8]{luximono}
+\usepackage[margin=2.84cm]{geometry}
+\usepackage{fancybox}
+\usepackage{xcolor}
+\def\listofitems{\textsf{\loiname}\xspace}
+\def\eTeX{\hbox{$\varepsilon$-\TeX}}
+\makeatletter
+\def\code{\expandafter\code@i\string}
+\def\code@i#1{%
+	\begingroup
+		\par\nobreak\medskip\parindent0pt
+		\leftskip.1\linewidth
+		\catcode`\^^I 13 \begingroup\lccode`\~`\^^I \lowercase{\endgroup\def~{\leavevmode\space\space\space\space}}%
+		\let\do\@makeother \dospecials
+		\ttfamily\small\@noligs
+		\obeylines\obeyspaces
+		\def\code@ii##1#1{##1\par\medbreak\endgroup}%
+		\code@ii
+}
+\long\def\grab@toks#1\relax{\gdef\right@content{#1}}
+
+\newcommand\disable@lig[1]{%
+	\catcode`#1\active
+	\begingroup
+		\lccode`\~`#1\relax
+		\lowercase{\endgroup\def~{\leavevmode\kern\z@\string#1}}%
+}
+
+\newcommand\exemple[1][65]{%
+	\edef\par@@indent{\the\parindent}%
+	\par\nobreak\vskip5pt \noindent
+	\def\part@coeff{#1}%
+	\relax\leavevmode\null
+	\bgroup
+		\let\do\@makeother\dospecials
+		\catcode`\^^M\active \catcode`\ \active
+		\begingroup
+			\lccode`\~`\ \lowercase{\def~{ {}}}%
+			\lccode`\~`\^^M\lowercase{\endgroup\def~{\par\noexpand\leavevmode}}%
+		\@makeother:\disable@lig,\disable@lig-%
+		\exemple@@
+}
+
+\newcommand\exemple@@[1]{%
+	\def\@tempa##1#1{%
+		\xdef\left@content{##1}%
+		\egroup
+		\def\right@content{##1}%
+		\begingroup
+			\newlinechar`\^^M\everyeof{\relax}%
+			\expandafter\grab@toks\scantokens\expandafter{\right@content}%
+		\endgroup
+		\exemple@@@
+		}%
+	\@tempa
+}
+
+\begingroup
+\catcode`#=12
+\gdef\exemple@@@{%
+	\begingroup
+      \fboxsep1pt\relax
+		\edef\part@left{\the\dimexpr0.\part@coeff\linewidth-\fboxsep-\fboxrule}%
+		\edef\part@right{\the\dimexpr\linewidth-0.\part@coeff\linewidth-\fboxsep-\fboxrule}%
+		\fbox{%
+			\parbox[c]\part@left{\vskip5pt\relax\ttfamily\footnotesize\left@content\vskip5pt}%
+			\parbox[c]\part@right{\vskip5pt\relax\normalfont\footnotesize\right@content\vskip5pt}%
+		}%
+		\vskip7.5pt\relax
+	\endgroup
+}
+\endgroup
+\begingroup
+	\catcode`\<13 \catcode`\>13
+	\gdef\verb{\relax\ifmmode\hbox\else\leavevmode\null\fi
+		\bgroup
+			\verb@eol@error \let\do\@makeother \dospecials
+			\verbatim@font\@noligs
+			\catcode`\<13 \catcode`\>13 \def<{\begingroup$\langle$\itshape}\def>{$\rangle$\endgroup}%
+			\@ifstar\@sverb\@verb}
+\endgroup
+\makeatother
+% FOR AMERICAN-ENGLISH VERSION
+\usepackage{setspace}
+\setstretch{1.02}
+\usepackage{enumitem}
+\newcommand\no[1]{number #1}
+\let\bsc\textsc
+\def\americanloidate{\expandafter\americanloidatei\loidate/}
+\def\americanloidatei#1/#2/#3/{#3 \ifcase #2 \or January\or February\or March\or April\or May\or 
+  June\or July\or August\or September\or October\or November\or December\fi{} #1}
+%\newcommand\flag[1]{\textcolor{red}{#1}}% DIAGNOSTIC FLAG FOR FURTHER TRANSLATION
+%\newcommand\cflag[1]{\textcolor{blue}{#1}}% DIAGNOSTIC FLAG FOR FURTHER TRANSLATION
+%
+\begin{document}
+\parindent=0pt
+\thispagestyle{empty}
+\begin{titlepage}
+	\renewcommand\thefootnote{\fnsymbol{footnote}}
+	\begingroup
+		\centering
+		\null\vskip.25\vsize
+		{\large\bfseries Package\par \Huge \listofitems\par}
+		\bigbreak
+		v\loiver
+		\smallbreak
+		\americanloidate
+		\vskip1.5cm
+		{Christian \bsc{Tellechea}\footnote{\texttt{unbonpetit@openmailbox.org}}\par Steven B. \bsc{Segletes}\footnote{steven.b.segletes.civ@mail.mil}}
+		\par
+	\endgroup
+	\vskip2cm
+	\leftskip=.2\linewidth \rightskip=.2\linewidth \small
+This simple package is designed to read a list of items whose
+  parsing character may be selected by the user. 
+Once the list is read, its items are stored in a structure that behaves 
+  as a dimensioned array.
+As such, it becomes very easy to access an item
+  in the list by its number. 
+For example, if the list is stored in the
+  macro \verb|\foo|, the item \no3 is designated by \verb|\foo[3]|.
+
+A component may, in turn, be a list with a parsing delimiter different from
+  the parent list, paving the way for
+  nesting and employing a syntax reminiscent of an array of
+  several dimensions of the type \verb|\foo[3,2]| to access the item \no2
+  of the list contained within the item \no3 of the top-tier list.
+\end{titlepage}
+\def\listofitems{\textsf\loiname\xspace}
+
+\section{Preface}
+
+\begin{sloppypar}
+This package loads no external packages, must be used with the 
+  \eTeX{} engine, and must be called in (pdf)(Xe)(lua)\LaTeX{} with
+  the invocation
+\code|\usepackage{listofitems}|
+\end{sloppypar}
+
+and under (pdf)(Xe)(Lua)\TeX {} by way of 
+\code|\input listofitems.tex|
+
+\section{Read a Simple List}
+\paragraph{Set the parsing character}
+The default parsing character is the comma and if we want change it, we must do so
+  before reading a list of items, with the definition 
+  \verb|\setsepchar{<parse-character>}|. 
+A \verb|<parse-character>| is a set of tokens which possess catcodes different from 
+  1 and 2 (the opening and closing braces), 14 (usually 
+  \verb|%|) and 15. 
+The token of catcode 6 (usually \verb|#|) is accepted only if it
+  is followed by an integer, denoting the argument of a macro; 
+In no case should this token be provided alone as the \verb|<parse-character>|. 
+Commands can be included in this set of tokens,
+including the \TeX{} primitive \verb|\par|.%
+\smallbreak
+The parsing-character \verb|<delimiter>| ``\verb-/-'' is reserved by default 
+  for nested lists (see page 3). %\ref{nested.list.delimiters}). 
+It is therefore not proper to write "\verb-\setsepchar{/}-" 
+  because the \listofitems{} package would misunderstand that you want to read 
+  a nested list.
+To set ``\verb-/-'' as the \verb|<parse-character>| for a simple list,
+  it is necessary, using the optional argument, to choose
+  a different parsing-character \verb|<delimiter>| for nested lists, 
+  for example ``\verb|.|'', and write ``\verb+\setsepchar[.]{/}+''.
+\medbreak
+
+\begin{sloppypar}
+It is not possible to select \verb-|- as the \verb|<delimiter>| because it would 
+  conflict with the logical \textbf{OR}, denoted ``\verb-||-'' (see below).
+However, one can work around this limitation, at one's own peril, writing 
+  ``\verb-\setsepchar{{|}}-''.
+\end{sloppypar}
+
+\paragraph{Read a list}
+To read the list of items, the \verb|\readlist<macro-list>{<list>}| should be called. 
+In so doing, the \verb|<list>| is read and the items are stored in a macro, denoted
+  \verb|<macro-list>| which therefore acts as a table with the items of the
+  \verb|<list>|. 
+If braces appear as part of a list item, they
+  \emph{must} be balanced.
+Tokens possessing the catcodes 6, 14 and 15 are not allowed in the lists.
+
+For example, to set the \verb|<macro-list>| named \verb|\foo|, we can write
+\code|\setsepchar{,}
+\readlist\foo{12,abc, x y ,{\bfseries z}, ,\TeX,,!}|
+\setsepchar{,}
+\readlist\foo{12,abc, x y ,{\bfseries z}, ,\TeX,,!}
+
+If the \verb|<list>| is contained in a macro, then this macro is expanded. 
+Therefore, we can simply employ the syntax 
+  \verb|\readlist<macro-list><macro>|
+as in
+
+\code|\setsepchar{,}
+\def\List{12,abc, x y ,{\bfseries z}, ,\TeX,,!}
+\readlist\foo\List|
+
+\paragraph{Access an item}
+The macro \verb|\foo| \emph{requires} a numeric argument in square brackets, 
+  which we symbolically denote as $i$, indicating the rank of the item 
+  you wish to access. 
+So \verb|\foo[1]| is\footnote{\texttt{\textbackslash 
+  foo[}$i$\texttt] requires 2 expansions to give the item.} ``\verb|12|''. Similarly, \verb|\foo[4]| is 
+  ``\verb|{\bfseries z}|''.
+
+The number $i$ can also be negative in which case the counting is done from the end
+  of the list: $-1$ represents the last item, $-2$ the penultimate, etc. 
+If the number of items is $n$, then the argument $-n$ is the first item.
+\medbreak
+
+In general, if a \verb|<list>| has a length $n$, then the index $i$ can be in the 
+  interval $[1\,;n]$ or $[-n\,;-1]$. 
+Otherwise, a compilation error occurs.
+
+If the index is empty, \verb|\foo[]| produces the complete \verb|<list>|.
+
+\paragraph{Select several possible parsing characters}
+To specify several possible separators, use the \textbf{OR} operator,
+  denoted ``\verb-||-''. 
+One can use this feature, for example, to isolate the terms in an
+  algebraic sum:
+
+\exemple/\setsepchar{+||-}
+\readlist\term{17-8+4-11}
+1) \term[1]\par
+2) \term[2]\par
+3) \term[3]\par
+4) \term[4]/
+
+\paragraph{Number of items}
+If we write \verb|\readlist<macro-list>{<list>}|, then the macro \verb|<macro-list>len|
+  con\-tains\footnote{That is to say, it is 
+  purely expandable and grows into a number.}
+  the number of the items in \verb|<list>|.
+In the example with \verb|\foo|, the macro \verb|\foolen| expands to \foolen.
+
+\paragraph{View all items}
+For purposes of debugging, the macro \verb|\showitems<macro-list>| includes all 
+  items from a list, while the star version displays these items ``detokenized.''
+  \footnote{The primitive \texttt{\string\detokenize}, conducting this 
+  decomposition, inserts a space after each control sequence.}
+
+\exemple/\showitems\foo\par
+\showitems*\foo/
+
+The presentation of each list item is assigned to the macro \verb|\showitemsmacro| 
+  whose code is
+
+\code|\newcommand\showitemsmacro[1]{%
+	\begingroup\fboxsep=0.25pt \fboxrule=0.5pt \fbox{\strut#1}\endgroup
+	\hskip0.25em\relax}|
+
+It is therefore possible ---~and desirable~--- to redefine it if we desire a
+ different presentation effect.\medbreak
+
+The macro \verb|\fbox| and associated dimensions \verb|\fboxsep| and 
+  \verb|\fboxrule|, are defined by \listofitems, when \textit{not} 
+  compiled under \LaTeX{}, to achieve the same result \textit{as if}
+  performed under \LaTeX.
+
+\paragraph{Suppression of extreme (leading/trailing) spaces}
+By default, \listofitems reads and retains the spaces located at 
+  the beginning and end of an item. 
+For these spaces to be ignored when reading the \verb|<list>|, execute the starred 
+  version \verb|\readlist*<macro>{<list>}|:
+
+\exemple|\setsepchar{,}
+\readlist*\foo{12,abc, x y ,{\bfseries z}, ,\TeX,,!}
+\showitems\foo|
+
+\paragraph{Managing empty items}
+\begin{sloppypar}
+By default, the \listofitems package retains and accounts for empty items. 
+Thus, in the previous ex\-am\-ple, the 2nd expansion of \verb|\foo[7]| is empty. 
+For empty items of the list (i.e., those list items defined by two 
+  consecutive parsing delimiters) to be ignored, we must,
+  before invoking \verb|\readlist|,
+  execute the macro \verb|\ignoreemptyitems| . 
+To return to the default package behavior, simply execute the macro 
+  \verb|\reademptyitems|.
+\end{sloppypar}
+
+This option can be used alone or in combination with \verb|\readlist*|, 
+  in which case the suppression of extreme (leading/trailing) spaces occurs
+  \textit{before} \textsf{listofitems} ignores the empty list items:
+
+\exemple|\setsepchar{,}
+\ignoreemptyitems
+\readlist\foo{12,abc, x y ,{\bfseries z}, ,\TeX,,!}
+a) number of items = \foolen\par
+   \showitems\foo
+
+\readlist*\foo{12,abc, x y ,{\bfseries z}, ,\TeX,,!}
+b) number of items = \foolen\par
+   \showitems\foo|
+
+\paragraph{Iterate over a list}
+Once a list read by \verb|\readlist| and stored in a \verb|<macro-list>|, one may 
+  iterate over the list with the syntax
+  \verb|\foreachitem <variable> \in <macro-list>{<code>}|: 
+The \verb|<variable>| is a macro chosen by the user that will loop over the value 
+  of each item in the list.
+
+The macro \verb|<variable>cnt| represents the sequence number of the item in 
+  \verb|<variable>|.
+
+\exemple|\setsepchar{ }% parse-character = space
+\readlist\phrase{One phrase to test.}
+\foreachitem\word\in\phrase{List item number \wordcnt{}: \word\par}|
+
+\paragraph{Assign an item to a macro}
+The \verb|\itemtomacro<macro-list>[index]<macro>| assigns to the \verb|<macro>|
+  the item designated by \verb|<macro-list>[index]|. 
+The \verb|<macro>| thus defined is purely expandable provided that the tokens 
+  in the items are expandable.
+
+\exemple|\setsepchar{ }% parse-character = space
+\readlist\phrase{One phrase to test.}
+\itemtomacro\phrase[2]\aword
+\meaning\aword\par
+\itemtomacro\phrase[-1]\wordattheend
+\meaning\wordattheend|
+
+\section{Nested Lists}
+We speak of a list being ``nested'' when asking \listofitems to read a list where 
+  the items are, in turn, understood as being a list (implying a parsing
+  character different from the top-tier list). 
+The nesting depth is not limited, but in practice, a depth of 
+  2 or 3 will usually suffice.
+
+\paragraph{Defining the parsing characters}\label{nested.list.delimiters}
+To indicate that a list will be nested, so that 
+  the list parsing will be performed recursively, one must specify multiple
+  parsing characters, each corresponding to the particular tier of nesting.
+This list of parsing characters is itself given as a delimited list to
+  the macro \verb|\setsepchar|, with the syntax
+    \verb|\setsepchar[<delimiter>]{<delimited-list-of-parse-characters>}|.
+
+By default, the \verb|<delimiter>| is ``\texttt{/}''.
+Thus, writing
+
+\code|\setsepchar{\\/,/ }|
+
+indicates a recursive depth of 3, with the parsing-character list delimiter defaulting
+  to ``\texttt{/}'':
+
+\begin{itemize}[itemsep=0pt,topsep=0pt,partopsep=0pt,parsep=0pt,label=---]
+	\item Tier 1 items are parsed between ``\verb|\\|'' delimiters;
+	\item Tier 2 items are found within Tier 1 items, parsed between ``\verb|,|'' delimiters; 
+	\item finally, the Tier 3 items are found within Tier 2 items, parsed between the
+           ``\verb*| |'' delimiters.
+\end{itemize}
+
+The \verb|<depth>| of nesting is contained in the purely expandable macro \verb|\nestdepth|.
+
+\paragraph{Read and access list items}
+For nested lists, the use of
+  indices obey the following rules:
+
+\begin{itemize}[itemsep=0pt,topsep=0pt,partopsep=0pt,parsep=0pt,label=---]
+	\item \verb|[]| is the main list, i.e., the argument of \verb|\readlist|;
+	\item \verb|[<i>]| means the item \no\verb|<i>| of the main list;
+	\item \verb|[<i>,<j>]| means the item \no\verb|<j>| of the list 
+               mentioned in the previous point (a subitem);
+	\item \verb|[<i>,<j>,<k>]| means the item \no\verb|<k>| of the 
+                list mentioned in the previous point (a sub-subitem);
+	\item etc.
+\end{itemize}
+
+As in the case of a non-nested list, the index may be negative.
+
+To read items, the syntax of \verb|\readlist| is exactly the same as 
+  that for simple (non-nested) lists:
+
+\exemple|\setsepchar{\\/,/ }
+\readlist\baz{1,2 a b,3 c\\4 d e f,5,6\\7,,8, ,9 xy z}
+a) \string\baz[1] is \baz[1]\par
+b) \string\baz[1,1] is \baz[1,1]\par
+c) \string\baz[1,1,1] is \baz[1,1,1]\par
+b) \string\bar[1,2] is \baz[1,2]\par
+e) \string\baz[1,2,3] is \baz[1,2,3]\par
+f) \string\baz[-2,1,-1] is \baz[-2,1,-1]|
+
+\paragraph{The operator ``||''}
+This operator may be employed at any level of nesting.
+
+\exemple=\setsepchar[,]{+||-,*||/}
+\readlist\numbers{1+2*3-4/5*6}
+Term 1: \numbers[1]\par
+Term 2: \numbers[2] (factors: \numbers[2,1] and
+         \numbers[2,2])\par
+Term 3: \numbers[3] (factors: \numbers[3,1],
+         \numbers[3,2] and \numbers[3,3])=
+
+\paragraph{Number of list items}
+\begin{sloppypar}
+The macro \verb|\listlen<macro-list>[<index>]| requires 2 expansions
+  in order to
+  give the number of items in the list specified by the \verb|<index>|.
+The \verb|<depth>| of the \verb|<index>| must be strictly less than that
+  of the list.
+
+For the case where the \verb|<index>| is empty, 
+  \verb|\listlen<macro-list>[]|, with 2 expansions, yields the identical result 
+  as \verb|<macro-list>len| with 1 expansion.
+\end{sloppypar}
+
+\exemple|\setsepchar{\\/,/ }
+\readlist\baz{1,2 a b,3 c\\4 d e f,5,6\\7,,8, ,9 xy z}
+a) \bazlen\ or \listlen\baz[]\par
+b) \listlen\baz[1]\par
+c) \listlen\baz[2]\par
+d) \listlen\baz[3]\par
+e) \listlen\baz[3,1]\par
+f) \listlen\baz[3,4]\par% 2 empty items
+g) \listlen\baz[3,5]|
+
+\paragraph{Displaying list items}
+The macro \verb|\showitems<macrolist>[<index>]| displays items from the list specified by
+  \verb|<index>|, in the same manner as \verb|\listlen|.
+The \verb|<depth>| of the \verb|<index>| must be strictly less than 
+  that of the \verb|<list>|.
+
+\exemple|\setsepchar{\\/,/ }
+\readlist\baz{1,2 a b,3 c\\4 d e f,5,6\\7,,8, ,9 xy z}
+a) \showitems\baz[]\par
+b) \showitems\baz[1]\par
+c) \showitems\baz[2]\par
+d) \showitems\baz[3]\par
+e) \showitems\baz[3,1]\par
+f) \showitems\baz[3,4]\par% 2 empty items
+g) \showitems\baz[3,5]|
+
+
+
+\paragraph{Empty items and extreme (leading/trailing) spaces}
+The removal of empty items and/or leading/\allowbreak trailing spaces will occur in \emph{all} 
+  the items, regardless of the degree of nesting. 
+It is clear that a space, ``\verb*| |'', is useless as a parsing character if you want 
+  to use \verb|\readlist*|. 
+Therefore, in the following example, ``\verb|*|'' is instead selected as the (3rd-tier)
+  parsing character. 
+
+Further, we remove only the extreme spaces, but retain empty items.
+
+\exemple|\setsepchar{\\/,/*}
+\readlist*\baz{1, 2*a*b ,3*c\\4*d*e*f,5,6\\7,,8, ,9* xy *z}
+a) \showitems\baz[]\par
+b) \showitems\baz[1]\par
+c) \showitems\baz[2]\par
+d) \showitems\baz[3]\par
+e) \showitems\baz[3,1]\par
+f) \showitems\baz[3,4]\par
+g) \showitems\baz[3,5]% "xy" without extreme spaces|
+
+\paragraph{Iterate over a list}
+The syntax \verb|\foreachitem <variable> \in <macro>[<index>]{<code>}| 
+  remains valid where now the \verb|<index>| specifies the item 
+  (understood as a list) on which to iterate.
+The \verb|<depth>| of the \verb|<index>| must be strictly less than 
+  that of the \verb|<list>|.
+
+
+\paragraph{Assign an item to a macro}
+The syntax \verb|\itemtomacro<macro-list>[<index>]<macro>| remains valid to assign 
+  to \verb|<macro>| the item specified by \verb|<macro-list>[<index>]|.
+
+\exemple[55]|\setsepchar[,]{\\, }
+\readlist\poem{There once was a runner named Dwight\\%
+Who could speed even faster than light.\\%
+He set out one day\\%
+In a relative way\\%
+And returned on the previous night.}
+\itemtomacro\poem[2]\verse
+2nd verse = \verse
+
+\itemtomacro\poem[2,-4]\word
+A word = \word|
+\end{document}
\ No newline at end of file
-- 
cgit v1.2.3

