From ded55718c96e299414c7688764a8d0d045a2fa44 Mon Sep 17 00:00:00 2001 From: Karl Berry 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{}|. +A \verb|| 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||. +Commands can be included in this set of tokens, +including the \TeX{} primitive \verb|\par|.% +\smallbreak +The parsing-character \verb|| ``\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|| for a simple list, + it is necessary, using the optional argument, to choose + a different parsing-character \verb|| for nested lists, + for example ``\verb|.|'', and write ``\verb+\setsepchar[.]{/}+''. +\medbreak + +\begin{sloppypar} +It is not possible to select \verb-|- as the \verb|| 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{}| should be called. +In so doing, the \verb|| is read and the items are stored in a macro, denoted + \verb|| which therefore acts as a table with the items of the + \verb||. +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|| 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|| is contained in a macro, then this macro is expanded. +Therefore, we can simply employ the syntax + \verb|\readlist| +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|| 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||. + +\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{}|, then the macro \verb|len| + con\-tains\footnote{That is to say, it is + purely expandable and grows into a number.} + the number of the items in \verb||. +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| 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||, execute the starred + version \verb|\readlist*{}|: + +\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||, one may + iterate over the list with the syntax + \verb|\foreachitem \in {}|: +The \verb|| is a macro chosen by the user that will loop over the value + of each item in the list. + +The macro \verb|cnt| represents the sequence number of the item in + \verb||. + +\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[index]| assigns to the \verb|| + the item designated by \verb|[index]|. +The \verb|| 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[]{}|. + +By default, the \verb|| 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|| 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|[]| means the item \no\verb|| of the main list; + \item \verb|[,]| means the item \no\verb|| of the list + mentioned in the previous point (a subitem); + \item \verb|[,,]| means the item \no\verb|| 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[]| requires 2 expansions + in order to + give the number of items in the list specified by the \verb||. +The \verb|| of the \verb|| must be strictly less than that + of the list. + +For the case where the \verb|| is empty, + \verb|\listlen[]|, with 2 expansions, yields the identical result + as \verb|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[]| displays items from the list specified by + \verb||, in the same manner as \verb|\listlen|. +The \verb|| of the \verb|| must be strictly less than + that of the \verb||. + +\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 \in []{}| + remains valid where now the \verb|| specifies the item + (understood as a list) on which to iterate. +The \verb|| of the \verb|| must be strictly less than + that of the \verb||. + + +\paragraph{Assign an item to a macro} +The syntax \verb|\itemtomacro[]| remains valid to assign + to \verb|| the item specified by \verb|[]|. + +\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